[llvm] r367655 - [LLVM][Alignment] Update documentation
Guillaume Chatelet via llvm-commits
llvm-commits at lists.llvm.org
Fri Aug 2 00:14:20 PDT 2019
Author: gchatelet
Date: Fri Aug 2 00:14:20 2019
New Revision: 367655
URL: http://llvm.org/viewvc/llvm-project?rev=367655&view=rev
Log:
[LLVM][Alignment] Update documentation
Reviewers: aprantl
Subscribers: llvm-commits
Tags: #llvm
Differential Revision: https://reviews.llvm.org/D65558
Modified:
llvm/trunk/include/llvm/Support/Alignment.h
Modified: llvm/trunk/include/llvm/Support/Alignment.h
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/include/llvm/Support/Alignment.h?rev=367655&r1=367654&r2=367655&view=diff
==============================================================================
--- llvm/trunk/include/llvm/Support/Alignment.h (original)
+++ llvm/trunk/include/llvm/Support/Alignment.h Fri Aug 2 00:14:20 2019
@@ -34,13 +34,13 @@ namespace llvm {
#define ALIGN_CHECK_ISSET(decl) \
assert(decl.hasValue() && (#decl " should be defined"))
-// This struct is a compact representation of a valid (non-zero power of two)
-// alignment.
-// It is suitable for use as static global constants.
+/// This struct is a compact representation of a valid (non-zero power of two)
+/// alignment.
+/// It is suitable for use as static global constants.
struct Align {
private:
- uint8_t ShiftValue = 0; // The log2 of the required alignment.
- // ShiftValue is less than 64 by construction.
+ uint8_t ShiftValue = 0; /// The log2 of the required alignment.
+ /// ShiftValue is less than 64 by construction.
friend struct MaybeAlign;
friend unsigned Log2(Align);
@@ -54,10 +54,10 @@ private:
friend struct MaybeAlign decodeMaybeAlign(unsigned Value);
public:
- // Default is byte-aligned.
+ /// Default is byte-aligned.
Align() = default;
- // Do not perform checks in case of copy/move construct/assign, because the
- // checks have been performed when building `Other`.
+ /// Do not perform checks in case of copy/move construct/assign, because the
+ /// checks have been performed when building `Other`.
Align(const Align &Other) = default;
Align &operator=(const Align &Other) = default;
Align(Align &&Other) = default;
@@ -70,33 +70,33 @@ public:
assert(ShiftValue < 64 && "Broken invariant");
}
- // This is a hole in the type system and should not be abused.
- // Needed to interact with C for instance.
+ /// This is a hole in the type system and should not be abused.
+ /// Needed to interact with C for instance.
uint64_t value() const { return uint64_t(1) << ShiftValue; }
};
-// Treats the value 0 as a 1, so Align is always at least 1.
+/// Treats the value 0 as a 1, so Align is always at least 1.
inline Align assumeAligned(uint64_t Value) {
return Value ? Align(Value) : Align();
}
-// This struct is a compact representation of a valid (power of two) or
-// undefined (0) alignment.
+/// This struct is a compact representation of a valid (power of two) or
+/// undefined (0) alignment.
struct MaybeAlign : public llvm::Optional<Align> {
private:
using UP = llvm::Optional<Align>;
public:
- // Default is undefined.
+ /// Default is undefined.
MaybeAlign() = default;
- // Do not perform checks in case of copy/move construct/assign, because the
- // checks have been performed when building `Other`.
+ /// Do not perform checks in case of copy/move construct/assign, because the
+ /// checks have been performed when building `Other`.
MaybeAlign(const MaybeAlign &Other) = default;
MaybeAlign &operator=(const MaybeAlign &Other) = default;
MaybeAlign(MaybeAlign &&Other) = default;
MaybeAlign &operator=(MaybeAlign &&Other) = default;
- // Use llvm::Optional<Align> constructor.
+ /// Use llvm::Optional<Align> constructor.
using UP::UP;
explicit MaybeAlign(uint64_t Value) {
@@ -106,78 +106,69 @@ public:
emplace(Value);
}
- // For convenience, returns a valid alignment or 1 if undefined.
+ /// For convenience, returns a valid alignment or 1 if undefined.
Align valueOrOne() const { return hasValue() ? getValue() : Align(); }
};
-// -----------------------------------------------------------------------------
-// isAligned: Checks that SizeInBytes is a multiple of the alignment.
-// -----------------------------------------------------------------------------
-
+/// Checks that SizeInBytes is a multiple of the alignment.
inline bool isAligned(Align Lhs, uint64_t SizeInBytes) {
return SizeInBytes % Lhs.value() == 0;
}
-// Returns false if the alignment is undefined.
+/// Checks that SizeInBytes is a multiple of the alignment.
+/// Returns false if the alignment is undefined.
inline bool isAligned(MaybeAlign Lhs, uint64_t SizeInBytes) {
ALIGN_CHECK_ISSET(Lhs);
return SizeInBytes % (*Lhs).value() == 0;
}
-// -----------------------------------------------------------------------------
-// alignTo: Returns a multiple of A needed to store `Size` bytes.
-// -----------------------------------------------------------------------------
-
+/// Returns a multiple of A needed to store `Size` bytes.
inline uint64_t alignTo(uint64_t Size, Align A) {
return (Size + A.value() - 1) / A.value() * A.value();
}
-// Returns `Size` if current alignment is undefined.
+/// Returns a multiple of A needed to store `Size` bytes.
+/// Returns `Size` if current alignment is undefined.
inline uint64_t alignTo(uint64_t Size, MaybeAlign A) {
return A ? alignTo(Size, A.getValue()) : Size;
}
-// -----------------------------------------------------------------------------
-// log2: Returns the log2 of the alignment.
-// e.g. Align(16).log2() == 4
-// -----------------------------------------------------------------------------
-
+/// Returns the log2 of the alignment.
inline unsigned Log2(Align A) { return A.ShiftValue; }
+/// Returns the log2 of the alignment.
/// \pre A must be defined.
inline unsigned Log2(MaybeAlign A) {
ALIGN_CHECK_ISSET(A);
return Log2(A.getValue());
}
-// -----------------------------------------------------------------------------
-// commonAlignment: returns the alignment that satisfies both alignments.
-// Same semantic as MinAlign.
-// -----------------------------------------------------------------------------
-
+/// Returns the alignment that satisfies both alignments.
+/// Same semantic as MinAlign.
inline Align commonAlignment(Align A, Align B) { return std::min(A, B); }
+/// Returns the alignment that satisfies both alignments.
+/// Same semantic as MinAlign.
inline Align commonAlignment(Align A, uint64_t Offset) {
return Align(MinAlign(A.value(), Offset));
}
+/// Returns the alignment that satisfies both alignments.
+/// Same semantic as MinAlign.
inline MaybeAlign commonAlignment(MaybeAlign A, MaybeAlign B) {
return A && B ? commonAlignment(*A, *B) : A ? A : B;
}
+/// Returns the alignment that satisfies both alignments.
+/// Same semantic as MinAlign.
inline MaybeAlign commonAlignment(MaybeAlign A, uint64_t Offset) {
return MaybeAlign(MinAlign((*A).value(), Offset));
}
-// -----------------------------------------------------------------------------
-// Encode/Decode
-// -----------------------------------------------------------------------------
-
-// Returns a more compact representation of the alignment.
-// An undefined MaybeAlign is encoded as 0.
+/// Returns a representation of the alignment that encodes undefined as 0.
inline unsigned encode(MaybeAlign A) { return A ? A->ShiftValue + 1 : 0; }
-// Dual operation of the encode function above.
+/// Dual operation of the encode function above.
inline MaybeAlign decodeMaybeAlign(unsigned Value) {
if (Value == 0)
return MaybeAlign();
@@ -186,17 +177,11 @@ inline MaybeAlign decodeMaybeAlign(unsig
return Out;
}
-// Returns a more compact representation of the alignment.
-// The encoded value is positive by definition.
-// e.g. Align(1).encode() == 1
-// e.g. Align(16).encode() == 5
+/// Returns a representation of the alignment, the encoded value is positive by
+/// definition.
inline unsigned encode(Align A) { return encode(MaybeAlign(A)); }
-// -----------------------------------------------------------------------------
-// Comparisons
-// -----------------------------------------------------------------------------
-
-// Comparisons between Align and scalars. Rhs must be positive.
+/// Comparisons between Align and scalars. Rhs must be positive.
inline bool operator==(Align Lhs, uint64_t Rhs) {
ALIGN_CHECK_ISPOSITIVE(Rhs);
return Lhs.value() == Rhs;
@@ -222,7 +207,7 @@ inline bool operator>(Align Lhs, uint64_
return Lhs.value() > Rhs;
}
-// Comparisons between MaybeAlign and scalars.
+/// Comparisons between MaybeAlign and scalars.
inline bool operator==(MaybeAlign Lhs, uint64_t Rhs) {
return Lhs ? (*Lhs).value() == Rhs : Rhs == 0;
}
@@ -250,7 +235,7 @@ inline bool operator>(MaybeAlign Lhs, ui
return (*Lhs).value() > Rhs;
}
-// Comparisons operators between Align.
+/// Comparisons operators between Align.
inline bool operator==(Align Lhs, Align Rhs) {
return Lhs.ShiftValue == Rhs.ShiftValue;
}
@@ -270,7 +255,7 @@ inline bool operator>(Align Lhs, Align R
return Lhs.ShiftValue > Rhs.ShiftValue;
}
-// Comparisons operators between Align and MaybeAlign.
+/// Comparisons operators between Align and MaybeAlign.
inline bool operator==(Align Lhs, MaybeAlign Rhs) {
ALIGN_CHECK_ISSET(Rhs);
return Lhs.value() == (*Rhs).value();
@@ -296,7 +281,7 @@ inline bool operator>(Align Lhs, MaybeAl
return Lhs.value() > (*Rhs).value();
}
-// Comparisons operators between MaybeAlign and Align.
+/// Comparisons operators between MaybeAlign and Align.
inline bool operator==(MaybeAlign Lhs, Align Rhs) {
ALIGN_CHECK_ISSET(Lhs);
return Lhs && (*Lhs).value() == Rhs.value();
@@ -322,10 +307,6 @@ inline bool operator>(MaybeAlign Lhs, Al
return Lhs && (*Lhs).value() > Rhs.value();
}
-// -----------------------------------------------------------------------------
-// Division
-// -----------------------------------------------------------------------------
-
inline Align operator/(Align Lhs, uint64_t Divisor) {
assert(llvm::isPowerOf2_64(Divisor) &&
"Divisor must be positive and a power of 2");
More information about the llvm-commits
mailing list