...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
The alignment function is used to obtain a pointer to the first address within the specified buffer that is a multiple of the specified alignment value. This function exists in the C++11 standard library but is provided in this library for those C++11 and C++03 library implementations which do not yet support it.
namespace boost { namespace alignment { void* align(std::size_t alignment, std::size_t size, void*& ptr, std::size_t& space); } }
void* align(std::size_t alignment, std::size_t size, void*& ptr, std::size_t& space);
Effects: If it is possible to fit
size
bytes of storage aligned byalignment
into the buffer pointed to byptr
with lengthspace
, the function updatesptr
to point to the first possible address of such storage and decreasesspace
by the number of bytes used for alignment. Otherwise, the function does nothing.Requires:
alignment
shall be a fundamental alignment value or an extended alignment value, and shall be a power of twoptr
shall point to contiguous storage of at least space bytesReturns: A null pointer if the requested aligned buffer would not fit into the available space, otherwise the adjusted value of
ptr
.Note: The function updates its
ptr
andspace
arguments so that it can be called repeatedly with possibly differentalignment
andsize
arguments for the same buffer.
The aligned allocation function is a replacement for ::operator new(std::size_t, const std::no_throw_t&)
that allows requesting aligned memory.
The deallocation function replaces the corresponding ::operator delete(void*)
function. This functionality is not yet provided by the C++ standard.
namespace boost { namespace alignment { void* aligned_alloc(std::size_t alignment, std::size_t size); void aligned_free(void* ptr); } }
void* aligned_alloc(std::size_t alignment, std::size_t size);
Effects: Allocates space for an object whose alignment is specified by
alignment
, whose size is specified bysize
, and whose value is indeterminate. The value ofalignment
shall be a power of two.Requires:
alignment
shall be a power of two.Returns: A null pointer or a pointer to the allocated space.
Note: On certain platforms, the alignment may be rounded up to
alignof(void*)
and the space allocated may be slightly larger thansize
bytes, by an additionalsizeof(void*)
andalignment -
1 bytes.
void aligned_free(void* ptr);
Effects: Causes the space pointed to by
ptr
to be deallocated, that is, made available for further allocation. Ifptr
is a null pointer, no action occurs. Otherwise, if the argument does not match a pointer earlier returned by thealigned_alloc
function, or if the space has been deallocated by a call toaligned_free
, the behavior is undefined.Requires:
ptr
is a null pointer or a pointer earlier returned by thealigned_alloc
function that has not been deallocated by a call toaligned_free
.Returns: The
aligned_free
function returns no value.
The aligned allocator is a replacement for the default allocator, std::allocator
,
that supports value types which are over-aligned. It also allows specifying
a minimum alignment value used for all allocations, via the optional template
parameter. An alignment aware allocator is not yet provided by the C++ standard.
![]() |
Tip |
---|---|
Using the aligned allocator with a minimum alignment value is generally only suitable with containers that are not node-based such as vector. With node-based containers, such as list, the node object would have the minimum alignment instead of the value type object. |
namespace boost { namespace alignment { template<class T, std::size_t Alignment = 1> class aligned_allocator; template<std::size_t Alignment> class aligned_allocator<void, Alignment>; template<class T1, class T2, std::size_t Alignment> bool operator==(const aligned_allocator<T1, Alignment>&, const aligned_allocator<T2, Alignment>&) noexcept; template<class T1, class T2, std::size_t Alignment> bool operator!=(const aligned_allocator<T1, Alignment>&, const aligned_allocator<T2, Alignment>&) noexcept; } }
template<class T, std::size_t Alignment = 1> class aligned_allocator { public: typedef T value_type; typedef T* pointer; typedef const T* const_pointer; typedef void* void_pointer; typedef const void* const_void_pointer; typedef std::size_t size_type; typedef std::ptrdiff_t difference_type; typedef T& reference; typedef const T& const_reference; template<class U> struct rebind { typedef aligned_allocator<U, Alignment> other; }; aligned_allocator() noexcept = default; template<class U> aligned_allocator(const aligned_allocator<U, Alignment>&) noexcept; pointer address(reference value) const noexcept; const_pointer address(const_reference value) const noexcept; pointer allocate(size_type size, const_void_pointer = 0); void deallocate(pointer ptr, size_type); size_type max_size() const noexcept; template<class U, class... Args> void construct(U* ptr, Args&&... args); template<class U> void destroy(U* ptr); }; template<std::size_t Alignment> class aligned_allocator<void, Alignment> { public: typedef void value_type; typedef void* pointer; typedef const void* const_pointer; template<class U> struct rebind { typedef aligned_allocator<U, Alignment> other; }; };
Except for the destructor, member functions of the aligned allocator shall not introduce data races as a result of concurrent calls to those member functions from different threads. Calls to these functions that allocate or deallocate a particular unit of storage shall occur in a single total order, and each such deallocation call shall happen before the next allocation (if any) in this order.
pointer address(reference value) const noexcept;
Returns: The actual address of the object referenced by
value
, even in the presence of an overloadedoperator&
.
const_pointer address(const_reference value) const noexcept;
Returns: The actual address of the object referenced by
value
, even in the presence of an overloadedoperator&
.
pointer allocate(size_type size, const_void_pointer = 0);
Returns: A pointer to the initial element of an array of storage of size
n * sizeof(T)
, aligned on the maximum of the minimum alignment specified and the alignment of objects of typeT
.Remark: The storage is obtained by calling
aligned_alloc(std::size_t, std::size_t)
.Throws:
std::bad_alloc
if the storage cannot be obtained.
void deallocate(pointer ptr, size_type);
Requires:
ptr
shall be a pointer value obtained fromallocate()
.Effects: Deallocates the storage referenced by
ptr
.Remark: Uses
alignment::aligned_free(void*)
.
size_type max_size() const noexcept;
Returns: The largest value
N
for which the callallocate(N)
might succeed.
template<class U, class... Args> void construct(U* ptr, Args&&... args);
Effects:
::new((void*)ptr) U(std::forward<Args>(args)...)
template<class U> void destroy(U* ptr);
Effects:
ptr->~U()
template<class T1, class T2, std::size_t Alignment> bool operator==(const aligned_allocator<T1, Alignment>&, const aligned_allocator<T2, Alignment>&) noexcept;
Returns:
true
.
template<class T1, class T2, std::size_t Alignment> bool operator!=(const aligned_allocator<T1, Alignment>&, const aligned_allocator<T2, Alignment>&) noexcept;
Returns:
false
.
The aligned allocator adaptor can turn any existing C++03 or C++11 allocator into one that supports value types that are over-aligned. It also allows specifying a minimum alignment value used for all allocations, via the optional template parameter. An alignment aware allocator adaptor is not yet provided by the C++ standard.
![]() |
Tip |
---|---|
This adaptor can be used with a C++11 allocator whose pointer type is a smart pointer but the adaptor will expose only raw pointer types. |
namespace boost { namespace alignment { template<class Allocator, std::size_t Alignment = 1> class aligned_allocator_adaptor; template<class A1, class A2, std::size_t Alignment> bool operator==(const aligned_allocator_adaptor<A1, Alignment>& a1, const aligned_allocator_adaptor<A2, Alignment>& a2) noexcept; template<class A1, class A2, std::size_t Alignment> bool operator!=(const aligned_allocator_adaptor<A1, Alignment>& a1, const aligned_allocator_adaptor<A2, Alignment>& a2) noexcept; } }
template<class Allocator, std::size_t Alignment = 1> class aligned_allocator_adaptor : public Allocator { typedef std::allocator_traits<Allocator> Traits; // exposition only public: typedef typename Traits::value_type value_type; typedef typename Traits::size_type size_type; typedef value_type* pointer; typedef const value_type* const_pointer; typedef void* void_pointer; typedef const void* const_void_pointer; typedef std::ptrdiff_t difference_type; template<class U> struct rebind { typedef aligned_allocator_adaptor<typename Traits:: template rebind_alloc<U>, Alignment> other; }; aligned_allocator_adaptor() = default; template<class A> explicit aligned_allocator_adaptor(A&& alloc) noexcept; template<class U> aligned_allocator_adaptor(const aligned_allocator_adaptor<U, Alignment>& other) noexcept; Allocator& base() noexcept; const Allocator& base() const noexcept; pointer allocate(size_type size); pointer allocate(size_type size, const_void_pointer hint); void deallocate(pointer ptr, size_type size); };
aligned_allocator_adaptor() = default;
Effects: Value-initializes the
Allocator
base class.
template<class A> explicit aligned_allocator_adaptor(A&& alloc) noexcept;
Requires:
Allocator
shall be constructible fromA
.Effects: Initializes the
Allocator
base class withstd::forward<A>(alloc)
.
template<class U> aligned_allocator_adaptor(const aligned_allocator_adaptor<U, Alignment>& other) noexcept;
Requires:
Allocator
shall be constructible fromA
.Effects: Initializes the
Allocator
base class withother.base()
.
Allocator& base() noexcept;
Returns:
static_cast<Allocator&>(*this)
const Allocator& base() const noexcept;
Returns:
static_cast<const Allocator&>(*this)
pointer allocate(size_type size);
Returns: A pointer to the initial element of an array of storage of size
n * sizeof(value_type)
, aligned on the maximum of the minimum alignment specified and the alignment of objects of typevalue_type
.Remark: The storage is obtained by calling
A2::allocate
on an objecta2
, wherea2
of typeA2
is a rebound copy ofbase()
where itsvalue_type
is unspecified.Throws: Throws an exception thrown from
A2::allocate
if the storage cannot be obtained.
pointer allocate(size_type size, const_void_pointer hint);
Requires:
hint
is a value obtained by callingallocate()
on any equivalent aligned allocator adaptor object, or elsenullptr
.Returns: A pointer to the initial element of an array of storage of size
n * sizeof(value_type)
, aligned on the maximum of the minimum alignment specified and the alignment of objects of typevalue_type
.Remark: The storage is obtained by calling
A2::allocate
on an objecta2
, wherea2
of typeA2
is a rebound copy ofbase()
where itsvalue_type
is unspecified.Throws: Throws an exception thrown from
A2::allocate
if the storage cannot be obtained.
void deallocate(pointer ptr, size_type size);
Requires:
ptr
shall be a pointer value obtained fromallocate()
size
shall equal the value passed as the first argument to the invocation ofallocate()
which returnedptr
Effects: Deallocates the storage referenced by
ptr
.Note: Uses
A2::deallocate
on an objecta2
, wherea2
of typeA2
is a rebound copy ofbase()
where itsvalue_type
is unspecified.
template<class A1, class A2, std::size_t Alignment> bool operator==(const aligned_allocator_adaptor<A1, Alignment>& a1, const aligned_allocator_adaptor<A2, Alignment>& a2) noexcept;
Returns:
a1.base() == a2.base()
template<class A1, class A2, std::size_t Alignment> bool operator!=(const aligned_allocator_adaptor<A1, Alignment>& a1, const aligned_allocator_adaptor<A2, Alignment>& a2) noexcept;
Returns:
!(a1 == a2)
The aligned deleter class is convenient utility for destroying and then deallocating
constructed objects that were allocated using aligned allocation function
provided in this library. It serves as a replacement for the std::default_delete
class.
namespace boost { namespace alignment { class aligned_delete; } }
class aligned_delete { public: template<class T> void operator()(T* ptr) const noexcept(noexcept(ptr->~T())); };
template<class T> void operator()(T* ptr) const noexcept(noexcept(ptr->~T()));
Effects: Calls
~T()
onptr
to destroy the object and then callsalignment::aligned_free
onptr
to free the allocated memory.Note: If
T
is an incomplete type, the program is ill-formed.
The alignment type trait is used to query the alignment requirement of a type at compile time. It is provided by the C++11 standard library but is provided in this library for C++11 and C++03 implementations that do not provide this functionality.
namespace boost { namespace alignment { template<class T> struct alignment_of; } }
template<class T> struct alignment_of : std::integral_constant<std::size_t, unspecified> { };
Value: The alignment requirement of the type
T
as an integral constant of typestd::size_t
. WhenT
is a reference array type, the value shall be the alignment of the referenced type. WhenT
is an array type, the value shall be the alignment of the element type.Requires:
T
shall be a complete object type, or an array thereof, or a reference to one of those types.
The alignment validation function indicates whether or not an address is a multiple of the specified alignment value. It is generally useful in assertions to verify memory is correctly aligned. This functionality is not yet provided by the C++ standard.
namespace boost { namespace alignment { bool is_aligned(std::size_t alignment, const void* ptr) noexcept; } }
bool is_aligned(std::size_t alignment, const void* ptr) noexcept;
Requires:
alignment
shall be a power of two.Returns:
true
if the value ofptr
is aligned on the boundary specified byalignment
, otherwisefalse
.