Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

PrevUpHomeNext

Reference

Functions
Classes
Traits
Macros

void* align(std::size_t alignment, std::size_t size, void*& ptr, std::size_t& space);

Header

#include <boost/align/align.hpp>

Effects

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.

Requires
  • alignment shall be a power of two
  • ptr shall point to contiguous storage of at least space bytes
Returns
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 and space arguments so that it can be called repeatedly with possibly different alignment and sizearguments for the same buffer.

template<class T> constexpr T align_up(T value, std::size_t alignment) noexcept;

Header

#include <boost/align/align_up.hpp>

Constraints

T is not a pointer type

Requires

alignment shall be a power of two

Returns

A value at or after value that is a multiple of alignment.

template<class T> constexpr T align_down(T value, std::size_t alignment) noexcept;

Header

#include <boost/align/align_down.hpp>

Constraints

T is not a pointer type

Requires

alignment shall be a power of two

Returns

A value at or before value that is a multiple of alignment.

void* aligned_alloc(std::size_t alignment, std::size_t size);

Header

#include <boost/align/aligned_alloc.hpp>

Effects

Allocates space for an object whose alignment is specified by alignment, whose size is specified by size, and whose value is indeterminate.

Requires

alignment shall be a power of two.

Returns

A null pointer or a pointer to the allocated space.

Note

On certain platforms, the space allocated may be slightly larger than size bytes, to allow for alignment.

void aligned_free(void* ptr);

Header

#include <boost/align/aligned_alloc.hpp>

Effects

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.

Requires

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().

Returns

The aligned_free() function returns no value.

bool is_aligned(const volatile void* ptr, std::size_t alignment) noexcept;

Header

#include <boost/align/is_aligned.hpp>

Requires

alignment shall be a power of two.

Returns

true if ptr is aligned on the boundary specified by alignment, otherwise false.

template<class T> constexpr bool is_aligned(T value, std::size_t alignment) noexcept;

Header

#include <boost/align/is_aligned.hpp>

Constraints

T is not a pointer type

Requires

alignment shall be a power of two.

Returns

true if the value of value is aligned on the boundary specified by alignment, otherwise false.

template<class T, std::size_t Alignment = 1> class aligned_allocator;

Header

#include <boost/align/aligned_allocator.hpp>

Note

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.

Member types
  1. typedef T value_type;
  2. typedef T* pointer;
  3. typedef const T* const_pointer;
  4. typedef void* void_pointer;
  5. typedef const void* const_void_pointer;
  6. typedef std::add_lvalue_reference_t<T> reference;
  7. typedef std::add_lvalue_reference_t<const T> const_reference;
  8. typedef std::size_t size_type;
  9. typedef std::ptrdiff_t difference_type;
  10. typedef std::true_type propagate_on_container_move_assignment;
  11. typedef std::true_type is_always_equal;
  12. template<class U> struct rebind { typedef aligned_allocator<U, Alignment> other; };
Constructors

aligned_allocator() = default;

Effects

Constructs the allocator.

template<class U> aligned_allocator(const aligned_allocator<U, Alignment>&) noexcept;

Effects

Constructs the allocator.

Member functions

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 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 type T.

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 from allocate().

Effects

Deallocates the storage referenced by ptr.

Remark

Uses aligned_free(void*).

size_type max_size() const noexcept;

Returns

The largest value N for which the call allocate(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().

Global operators

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

template<class Allocator, std::size_t Alignment = 1> class aligned_allocator_adaptor;

Header

#include <boost/align/aligned_allocator_adaptor.hpp>

Note

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.

Member types
  1. typedef typename Allocator::value_type value_type;
  2. typedef value_type* pointer;
  3. typedef const value_type* const_pointer;
  4. typedef void* void_pointer;
  5. typedef const void* const_void_pointer;
  6. typedef std::size_t size_type;
  7. typedef std::ptrdiff_t difference_type;
  8. template<class U> struct rebind { typedef aligned_allocator_adaptor<typename std::allocator_traits<Allocator>::template rebind_alloc<U>, Alignment> other; };
Constructors

aligned_allocator_adaptor() = default;

Effects

Value-initializes the Allocator base class.

template<class A> aligned_allocator_adaptor(A&& alloc) noexcept;

Requires

Allocator shall be constructible from A.

Effects

Initializes the Allocator base class with std::forward<A>(alloc).

template<class U> aligned_allocator_adaptor(const aligned_allocator_adaptor<U, Alignment>& other) noexcept;

Requires

Allocator shall be constructible from A.

Effects

Initializes the Allocator base class with other.base().

Member functions

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 type value_type.

Remark

The storage is obtained by calling A2::allocate() on an object a2, where a2 of type A2 is a rebound copy of base() where its value_type is implementation defined.

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 calling allocate() on any equivalent allocator object, or else a null pointer.

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 type value_type.

Remark

The storage is obtained by calling A2::allocate() on an object a2, where a2 of type A2 is a rebound copy of base() where its value_type is an implementation defined.

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 from allocate()
  • size shall equal the value passed as the first argument to the invocation of allocate() which returned ptr.
Effects
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 implementation defined.

Global operators

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)

class aligned_delete;

Header

#include <boost/align/aligned_delete.hpp>

Member operators

template<class T> void operator()(T* ptr) noexcept(noexcept(ptr->~T()));

Effects

Calls ~T() on ptr to destroy the object and then calls aligned_free() on ptr to free the allocated memory.

Note

If T is an incomplete type, the program is ill-formed.

template<class T> struct alignment_of;

Header

#include <boost/align/alignment_of.hpp>

Value

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.

Requires

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)

Header

#include <boost/align/assume_aligned.hpp>

Requires
  • alignment shall be a power of two
  • ptr shall be mutable
Effects
ptr may be modified in an implementation specific way to inform the compiler of its alignment.

PrevUpHomeNext