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 size arguments for the same buffer.

constexpr std::size_t align_up(std::size_t value, std::size_t alignment) noexcept;

Header

#include <boost/align/align_up.hpp>

Requires

alignment shall be a power of two

Returns

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;

Header

#include <boost/align/align_down.hpp>

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 void* ptr, std::size_t alignment) noexcept;

constexpr bool is_aligned(std::size_t value, std::size_t alignment) noexcept;

Header

#include <boost/align/is_aligned.hpp>

Requires

alignment shall be a power of two.

Returns

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>;

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::size_t size_type;
  7. typedef std::ptrdiff_t difference_type;
  8. typedef T& reference;
  9. typedef const T& const_reference;
  10. template<class U> struct rebind { typedef aligned_allocator<U, Alignment> other; };
Constructors
  1. aligned_allocator() = default;

    Effects

    Constructs the allocator.

  2. 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.

  1. pointer address(reference value) const noexcept;

    Returns

    The actual address of the object referenced by value, even in the presence of an overloaded operator&.

  2. const_pointer address(const_reference value) const noexcept;

    Returns

    The actual address of the object referenced by value, even in the presence of an overloaded operator&.

  3. 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.

  4. 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*).

  5. size_type max_size() const noexcept;

    Returns

    The largest value N for which the call allocate(N) might succeed.

  6. template<class U, class... Args> void construct(U* ptr, Args&&... args);

    Effects

    ::new((void*)ptr) U(std::forward<Args>(args)...).

  7. template<class U> void destroy(U* ptr);

    Effects

    ptr->~U().

Global operators
  1. template<class T1, class T2, std::size_t Alignment> bool operator==(const aligned_allocator<T1, Alignment>&, const aligned_allocator<T2, Alignment>&) noexcept;

    Returns

    true

  2. 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
  1. aligned_allocator_adaptor() = default;

    Effects

    Value-initializes the Allocator base class.

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

  3. 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
  1. Allocator& base() noexcept;

    Returns

    static_cast<Allocator&>(*this)

  2. const Allocator& base() const noexcept;

    Returns

    static_cast<const Allocator&>(*this)

  3. 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 rebind copy of base() where its value_type is implementation defined.

    Throws

    Throws an exception thrown from A2::allocate() if the storage cannot be obtained.

  4. 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 rebind 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.

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

  2. 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
  1. 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