...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
void*
align(std::size_t alignment, std::size_t size, void*& ptr, std::size_t&
space);
#include <boost/align/align.hpp>
If it is possible to fit size
bytes of storage aligned by alignment
into the buffer pointed to by ptr
with length space
,
the function updates ptr
to point to the first possible address of such storage and decreases
space
by the number
of bytes used for alignment. Otherwise, the function does nothing.
alignment
shall
be a power of two
ptr
shall point
to contiguous storage of at least space
bytes
ptr
.
The function updates its ptr
and space
arguments
so that it can be called repeatedly with possibly different alignment
and size
arguments for the same buffer.
constexpr std::size_t align_up(std::size_t value, std::size_t alignment)
noexcept;
#include <boost/align/align_up.hpp>
alignment
shall be
a power of two
A value at or after value
that is a multiple of alignment
.
constexpr std::size_t align_down(std::size_t value, std::size_t alignment)
noexcept;
#include <boost/align/align_down.hpp>
alignment
shall be
a power of two
A value at or before value
that is a multiple of alignment
.
void*
aligned_alloc(std::size_t alignment, std::size_t size);
#include <boost/align/aligned_alloc.hpp>
Allocates space for an object whose alignment is specified by alignment
, whose size is specified
by size
, and whose
value is indeterminate.
alignment
shall be
a power of two.
A null pointer or a pointer to the allocated space.
On certain platforms, the space allocated may be slightly larger
than size
bytes,
to allow for alignment.
void aligned_free(void*
ptr);
#include <boost/align/aligned_alloc.hpp>
Causes the space pointed to by ptr
to be deallocated, that is, made available for further allocation.
If ptr
is a null
pointer, no action occurs. Otherwise, if the argument does not match
a pointer earlier returned by the aligned_alloc()
function, or if the space has been
deallocated by a call to aligned_free()
, the behavior is undefined.
ptr
is a null pointer
or a pointer earlier returned by the aligned_alloc()
function that has not been deallocated
by a call to aligned_free()
.
The aligned_free()
function returns no value.
bool is_aligned(const void* ptr, std::size_t alignment)
noexcept;
constexpr bool
is_aligned(std::size_t value, std::size_t alignment)
noexcept;
#include <boost/align/is_aligned.hpp>
alignment
shall be
a power of two.
true
if the value of
the first argument is aligned on the boundary specified by alignment
, otherwise false
.
template<class T, std::size_t Alignment =
1> class aligned_allocator;
template<std::size_t Alignment> class aligned_allocator<void, Alignment>;
#include <boost/align/aligned_allocator.hpp>
Using the aligned allocator with a minimum Alignment value is generally
only useful 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.
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;
Constructs the allocator.
template<class U> aligned_allocator(const aligned_allocator<U, Alignment>&)
noexcept;
Constructs the allocator.
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;
The actual address of the object referenced by value
, even in the presence
of an overloaded operator&
.
const_pointer address(const_reference
value)
const noexcept;
The actual address of the object referenced by value
, even in the presence
of an overloaded operator&
.
pointer allocate(size_type
size,
const_void_pointer =
0);
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 type T
.
The storage is obtained by calling aligned_alloc(std::size_t, std::size_t)
.
std::bad_alloc
if the storage cannot
be obtained.
void deallocate(pointer
ptr,
size_type);
ptr
shall be
a pointer value obtained from allocate()
.
Deallocates the storage referenced by ptr
.
Uses aligned_free(void*)
.
size_type max_size() const noexcept;
The largest value N
for which the call allocate(N)
might succeed.
template<class U, class... Args> void
construct(U* ptr, Args&&...
args);
::new((void*)ptr) U(std::forward<Args>(args)...)
.
template<class U> void
destroy(U* ptr);
ptr->~U()
.
template<class T1, class T2, std::size_t Alignment> bool
operator==(const aligned_allocator<T1, Alignment>&, const
aligned_allocator<T2, Alignment>&)
noexcept;
true
template<class T1, class T2, std::size_t Alignment> bool
operator!=(const aligned_allocator<T1, Alignment>&, const
aligned_allocator<T2, Alignment>&)
noexcept;
false
template<class Allocator, std::size_t Alignment =
1> class aligned_allocator_adaptor;
#include <boost/align/aligned_allocator_adaptor.hpp>
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.
typedef typename
Allocator::value_type value_type;
typedef value_type* pointer;
typedef const
value_type*
const_pointer;
typedef void* void_pointer;
typedef const
void*
const_void_pointer;
typedef std::size_t
size_type;
typedef std::ptrdiff_t
difference_type;
template<class U> struct
rebind {
typedef aligned_allocator_adaptor<typename
std::allocator_traits<Allocator>::template rebind_alloc<U>, Alignment> other; };
aligned_allocator_adaptor() = default;
Value-initializes the Allocator
base class.
template<class A> aligned_allocator_adaptor(A&& alloc) noexcept;
Allocator
shall
be constructible from A
.
Initializes the Allocator
base class with std::forward<A>(alloc)
.
template<class U> aligned_allocator_adaptor(const aligned_allocator_adaptor<U, Alignment>&
other)
noexcept;
Allocator
shall
be constructible from A
.
Initializes the Allocator
base class with other.base()
.
Allocator&
base()
noexcept;
static_cast<Allocator&>(*this)
const Allocator& base() const noexcept;
static_cast<const Allocator&>(*this)
pointer allocate(size_type
size);
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 type value_type
.
The storage is obtained by calling A2::allocate()
on an object a2
, where a2
of type A2
is
a rebind copy of base()
where its value_type
is implementation defined.
Throws an exception thrown from A2::allocate()
if the storage cannot be obtained.
pointer allocate(size_type
size,
const_void_pointer hint);
hint
is a value
obtained by calling allocate()
on any equivalent allocator
object, or else a null pointer.
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 type value_type
.
The storage is obtained by calling A2::allocate()
on an object a2
, where a2
of type A2
is
a rebind copy of base()
where its value_type
is an implementation defined.
Throws an exception thrown from A2::allocate()
if the storage cannot be obtained.
void deallocate(pointer
ptr,
size_type size);
ptr
shall
be a pointer value obtained from allocate()
size
shall
equal the value passed as the first argument to the invocation
of allocate()
which returned ptr
.
ptr
.
Uses A2::deallocate()
on an object a2
,
where a2
of type
A2
is a rebound
copy of base()
where its value_type
is implementation defined.
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;
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;
!(a1
== a2)
class aligned_delete;
#include <boost/align/aligned_delete.hpp>
template<class T> void
operator()(T* ptr) noexcept(noexcept(ptr->~T()));
Calls ~T()
on ptr
to destroy the object and then calls aligned_free()
on ptr
to free the allocated memory.
If T
is an incomplete
type, the program is ill-formed.
template<class T> struct alignment_of;
#include <boost/align/alignment_of.hpp>
The alignment requirement of the type T
as an integral constant of type std::size_t
.
When T
is a reference
array type, the value shall be the alignment of the referenced type.
When T
is an array
type, the value shall be the alignment of the element type.
T
shall be a complete
object type, or an array thereof, or a reference to one of those
types.
BOOST_ALIGN_ASSUME_ALIGNED(ptr, alignment)
#include <boost/align/assume_aligned.hpp>
alignment
shall
be a power of two
ptr
shall be
mutable
ptr
may be modified
in an implementation specific way to inform the compiler of its alignment.