123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149 |
- [/
- Copyright 2019 Glen Joseph Fernandes
- (glenjofe@gmail.com)
- Distributed under the Boost Software License, Version 1.0.
- (http://www.boost.org/LICENSE_1_0.txt)
- ]
- [section:alloc_construct alloc_construct, alloc_destroy]
- [simplesect Authors]
- * Glen Fernandes
- [endsimplesect]
- [section 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.
- [endsect]
- [section 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;
- }
- ```
- [endsect]
- [section 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 */
- ```
- [section Functions]
- [variablelist
- [[`template<class A, class T> void alloc_destroy(A& a, T* p);`]
- [[variablelist
- [[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);`]
- [[variablelist
- [[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);`]
- [[variablelist
- [[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);`]
- [[variablelist
- [[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);`]
- [[variablelist
- [[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);`]
- [[variablelist
- [[Requires]
- [[itemized_list
- [`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])`.]]]]]]
- [endsect]
- [endsect]
- [section 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.
- [endsect]
- [section 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.
- [endsect]
- [endsect]
|