alloc_construct, alloc_destroy

Overview

The header <boost/core/alloc_construct.hpp> provides function templates alloc_construct, alloc_construct_n, alloc_destroy, and alloc_destroy_n for allocator aware and exception safe construction and destruction of objects and arrays.

Example

The following example allocates storage for an array of n elements of T using an allocator a and constructs T elements in that storage. If any exception was thrown during construction of an element, the constructed elements are destroyed in reverse order.

template<class A>
auto create(A& a, std::size_t n)
{
    auto p = a.allocate(n);
    try {
        boost::alloc_construct_n(a, boost::to_address(p), n);
    } catch (...) {
        a.deallocate(p, n);
        throw;
    }
    return p;
}

Reference

namespace boost {

template<class A, class T>
void alloc_destroy(A& a, T* p);

template<class A, class T>
void alloc_destroy_n(A& a, T* p, std::size_t n);

template<class A, class T, class Args>
void alloc_construct(A& a, T* p, Args&&... args);

template<class A, class T>
void alloc_construct_n(A& a, T* p, std::size_t n);

template<class A, class T>
void alloc_construct_n(A& a, T* p, std::size_t n, const T* l, std::size_t m);

template<class A, class T, class I>
void alloc_construct_n(A& a, T* p, std::size_t n, I begin);

} /* boost */

Functions

template<class A, class T> void alloc_destroy(A& a, T* p);

Requires: A is an Allocator
Effects: std::allocator_traits<A>::destroy(a, p).

template<class A, class T> void alloc_destroy_n(A& a, T* p, std::size_t n);

Requires: A is an Allocator
Effects: Destroys each i-th element in reverse order by calling std::allocator_traits<A>::destroy(a, &p[i]).

template<class A, class T, class Args> void alloc_construct(A& a, T* p, Args&&... args);

Requires: A is an Allocator
Effects: std::allocator_traits<A>::construct(a, p, std::forward<Args>(args)...).

template<class A, class T> void alloc_construct_n(A& a, T* p, std::size_t n);

Requires: A is an Allocator
Effects: Constructs each i-th element in order by calling std::allocator_traits<A>::construct(a, &p[i]).
Remarks: If an exception is thrown destroys each already constructed j-th element in reverse order by calling std::allocator_traits<A>::destroy(a, &p[j]).

template<class A, class T> void alloc_construct_n(A& a, T* p, std::size_t n, const T* l, std::size_t m);

Requires: A is an Allocator
Effects: Constructs each i-th element in order by calling std::allocator_traits<A>::construct(a, &p[i], l[i % m]).
Remarks: If an exception is thrown destroys each already constructed j-th element in reverse order by calling std::allocator_traits<A>::destroy(a, &p[j]).

template<class A, class T, class I> void alloc_construct_n(A& a, T* p, std::size_t n, I begin);

Requires

A is an Allocator
I is an InputIterator

Effects

Constructs each i-th element in order by calling

std::allocator_traits<A>::construct(a, &p[i],
                      *begin++])

.

Remarks

If an exception is thrown destroys each already constructed j-th element in reverse order by calling std::allocator_traits<A>::destroy(a, &p[j]).

Compatibility

When BOOST_NO_CXX11_ALLOCATOR is defined, and the C++11 allocator model is not supported, these functions invoke constructors and destructors directly without going through the supplied allocator.

Acknowledgments

Glen Fernandes originally implemented this functionality in Boost.Smart_Ptr and later moved these functions to Boost.Core for use in other Boost libraries, such as Boost.Multi_Array and Boost.Histogram.

Boost C++ Libraries