Reference - 1.61.0

align

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.

Header <boost/align/align.hpp>

namespace boost {
  namespace alignment {
    void* align(std::size_t alignment, std::size_t size, void*& ptr,
      std::size_t& space);
  }
}

Function align

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 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 fundamental alignment value or an extended alignment value, and 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.

align_down

The directional alignment functions can be used with pointers or integral values to align down. This functionality is not yet provided by the C++ standard.

Header <boost/align/align_down.hpp>

namespace boost {
  namespace alignment {
    constexpr std::size_t align_down(std::size_t value, std::size_t
      alignment) noexcept;

    void* align_down(void* ptr, std::size_t alignment) noexcept;
  }
}

Function align_down

void* align_down(void* ptr, std::size_t alignment) noexcept;

Requires:

ptr shall point to contiguous storage with sufficient space for alignment

alignment shall be a power of two

Returns: A pointer value at or before ptr that is at least alignment bytes aligned.

align_up

The directional alignment functions can be used with pointers or integral values to align up. This functionality is not yet provided by the C++ standard.

Header <boost/align/align_up.hpp>

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

    void* align_up(void* ptr, std::size_t alignment) noexcept;
  }
}

Function align_up

void* align_up(void* ptr, std::size_t alignment) noexcept;

Requires:

ptr shall point to contiguous storage with sufficient space for alignment

alignment shall be a power of two

Returns: A pointer value at or after ptr that is at least alignment bytes aligned.

aligned_alloc and aligned_free

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.

Header <boost/align/aligned_alloc.hpp>

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

    void aligned_free(void* ptr);
  }
}

Function aligned_alloc

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 by size, and whose value is indeterminate. The value of alignment 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 than size bytes, by an additional sizeof(void*) and alignment - 1 bytes.

Function aligned_free

void aligned_free(void* ptr);

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.

aligned_allocator

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 `std::vector`. With node-based containers, such as list, the node object would have the minimum alignment instead of the value type object.

Header <boost/align/aligned_allocator.hpp>

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

Class template aligned_allocator

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

Members

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 overloaded operator&.

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

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 alignment::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()

Globals

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.

aligned_allocator_adaptor

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.

Header <boost/align/aligned_allocator_adaptor.hpp>

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

Class template aligned_allocator_adaptor

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

Constructors

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

Members

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 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 calling allocate() on any equivalent aligned allocator adaptor object, or else nullptr.

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

Globals

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)

aligned_delete

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.

Header <boost/align/aligned_delete.hpp>

namespace boost {
  namespace alignment {
    class aligned_delete;
  }
}

Class aligned_delete

class aligned_delete {
public:
    template<class T>
    void operator()(T* ptr) const noexcept(noexcept(ptr->~T()));
};

Members

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

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

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

alignment_of

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.

Header <boost/align/alignment_of.hpp>

namespace boost {
  namespace alignment {
    template<class T>
    struct alignment_of;

    template<class T>
    constexpr std::size_t alignment_of_v = alignment_of<T>::value;
  }
}

Type trait alignment_of

template<class T>
struct alignment_of;

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.

assume_aligned

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.

Header <boost/align/assume_aligned.hpp>

BOOST_ALIGN_ASSUME_ALIGNED(ptr, alignment)

Macro BOOST_ALIGN_ASSUME_ALIGNED

BOOST_ALIGN_ASSUME_ALIGNED(ptr, alignment)

Requires:

alignment shall be a power of two

ptr shall be mutable

Effect: ptr may be modified in an implementation specific way to inform the compiler of its alignment.

is_aligned

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.

Header <boost/align/is_aligned.hpp>

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

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

Function is_aligned

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

Requires: alignment shall be a power of two.

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