![]() |
Home | Libraries | People | FAQ | More |
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
sizebytes of storage aligned byalignmentinto the buffer pointed to byptrwith lengthspace, the function updatesptrto point to the first possible address of such storage and decreasesspaceby the number of bytes used for alignment. Otherwise, the function does nothing.Requires:
alignmentshall be a fundamental alignment value or an extended alignment value, and shall be a power of twoptrshall point to contiguous storage of at leastspacebytesReturns: 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
ptrandspacearguments so that it can be called repeatedly with possibly differentalignmentandsizearguments 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 ofalignmentshall be a power of two.Requires:
alignmentshall 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 thansizebytes, by an additionalsizeof(void*)andalignment - 1bytes.
void aligned_free(void* ptr);
Effects: Causes the space pointed to by
ptrto be deallocated, that is, made available for further allocation. Ifptris a null pointer, no action occurs. Otherwise, if the argument does not match a pointer earlier returned by thealigned_allocfunction, or if the space has been deallocated by a call toaligned_free, the behavior is undefined.Requires:
ptris a null pointer or a pointer earlier returned by thealigned_allocfunction that has not been deallocated by a call toaligned_free.Returns: The
aligned_freefunction 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 |
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() = 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_allocif the storage cannot be obtained.
void deallocate(pointer ptr, size_type);
Requires:
ptrshall 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
Nfor 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 can choose to 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 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
Allocatorbase class.
template<class A> explicit aligned_allocator_adaptor(A&& alloc) noexcept;
Requires:
Allocatorshall be constructible fromA.Effects: Initializes the
Allocatorbase class withstd::forward<A>(alloc).
template<class U> aligned_allocator_adaptor(const aligned_allocator_adaptor<U, Alignment>& other) noexcept;
Requires:
Allocatorshall be constructible fromA.Effects: Initializes the
Allocatorbase 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::allocateon an objecta2, wherea2of typeA2is a rebound copy ofbase()where itsvalue_typeis unspecified.Throws: Throws an exception thrown from
A2::allocateif the storage cannot be obtained.
pointer allocate(size_type size, const_void_pointer hint);
Requires:
hintis 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::allocateon an objecta2, wherea2of typeA2is a rebound copy ofbase()where itsvalue_typeis unspecified.Throws: Throws an exception thrown from
A2::allocateif the storage cannot be obtained.
void deallocate(pointer ptr, size_type size);
Requires:
ptrshall be a pointer value obtained fromallocate()sizeshall equal the value passed as the first argument to the invocation ofallocate()which returnedptrEffects: Deallocates the storage referenced by
ptr.
Note: Uses A2::deallocate
on an object a2, where a2 of type A2
is a rebound copy of base() where its value_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
the constructed objects that were allocated using aligned allocation function
provided in this library. It serves as a replacement for the std::default_delete
class for this case.
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()onptrto destroy the object and then callsalignment::aligned_freeonptrto free the allocated memory.Note: If
Tis 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 : integral_constant<std::size_t, alignof(T)> { };
Value: The alignment requirement of the type
Tas an integral constant of typestd::size_t. WhenTis a reference array type, the value shall be the alignment of the referenced type. WhenTis an array type, the value shall be the alignment of the element type.Requires:
Tshall be a complete object type, or an array thereof, or a reference to one of those types.
The alignment hint macro can be used to inform the compiler of the alignment of a memory block, to enable vectorizing or other compiler specific alignment related optimizations.
BOOST_ALIGN_ASSUME_ALIGNED(ptr, alignment)
BOOST_ALIGN_ASSUME_ALIGNED(ptr, alignment)
Requires:
alignmentshall be a power of twoptrshall be mutableEffect:
ptrmay be modified in an implementation specific way to inform the compiler of its alignment.
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:
alignmentshall be a power of two.Returns:
trueif the value ofptris aligned on the boundary specified byalignment, otherwisefalse.