• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1[/
2Copyright 2019 Glen Joseph Fernandes
3(glenjofe@gmail.com)
4
5Distributed under the Boost Software License, Version 1.0.
6(http://www.boost.org/LICENSE_1_0.txt)
7]
8
9[section:alloc_construct alloc_construct, alloc_destroy]
10
11[simplesect Authors]
12
13* Glen Fernandes
14
15[endsimplesect]
16
17[section Overview]
18
19The header <boost/core/alloc_construct.hpp> provides function templates
20`alloc_construct`, `alloc_construct_n`, `alloc_destroy`, and `alloc_destroy_n`
21for allocator aware and exception safe construction and destruction of objects
22and arrays.
23
24[endsect]
25
26[section Example]
27
28The following example allocates storage for an array of `n` elements of `T`
29using an allocator `a` and constructs `T` elements in that storage. If any
30exception was thrown during construction of an element, the constructed
31elements are destroyed in reverse order.
32
33```
34template<class A>
35auto create(A& a, std::size_t n)
36{
37    auto p = a.allocate(n);
38    try {
39        boost::alloc_construct_n(a, boost::to_address(p), n);
40    } catch (...) {
41        a.deallocate(p, n);
42        throw;
43    }
44    return p;
45}
46```
47
48[endsect]
49
50[section Reference]
51
52```
53namespace boost {
54
55template<class A, class T>
56void alloc_destroy(A& a, T* p);
57
58template<class A, class T>
59void alloc_destroy_n(A& a, T* p, std::size_t n);
60
61template<class A, class T, class Args>
62void alloc_construct(A& a, T* p, Args&&... args);
63
64template<class A, class T>
65void alloc_construct_n(A& a, T* p, std::size_t n);
66
67template<class A, class T>
68void alloc_construct_n(A& a, T* p, std::size_t n, const T* l, std::size_t m);
69
70template<class A, class T, class I>
71void alloc_construct_n(A& a, T* p, std::size_t n, I begin);
72
73} /* boost */
74```
75
76[section Functions]
77
78[variablelist
79[[`template<class A, class T> void alloc_destroy(A& a, T* p);`]
80[[variablelist
81[[Requires][`A` is an /Allocator/]]
82[[Effects][`std::allocator_traits<A>::destroy(a, p)`.]]]]]
83[[`template<class A, class T> void alloc_destroy_n(A& a, T* p,
84std::size_t n);`]
85[[variablelist
86[[Requires][`A` is an /Allocator/]]
87[[Effects]
88[Destroys each `i`-th element in reverse order by calling
89`std::allocator_traits<A>::destroy(a, &p[i])`.]]]]]
90[[`template<class A, class T, class Args> void alloc_construct(A& a, T* p,
91Args&&... args);`]
92[[variablelist
93[[Requires][`A` is an /Allocator/]]
94[[Effects]
95[`std::allocator_traits<A>::construct(a, p, std::forward<Args>(args)...)`.]]]]]
96[[`template<class A, class T> void alloc_construct_n(A& a, T* p,
97std::size_t n);`]
98[[variablelist
99[[Requires][`A` is an /Allocator/]]
100[[Effects]
101[Constructs each `i`-th element in order by calling
102`std::allocator_traits<A>::construct(a, &p[i])`.]]
103[[Remarks]
104[If an exception is thrown destroys each already constructed `j`-th element in
105reverse order by calling `std::allocator_traits<A>::destroy(a, &p[j])`.]]]]]
106[[`template<class A, class T> void alloc_construct_n(A& a, T* p, std::size_t n,
107const T* l, std::size_t m);`]
108[[variablelist
109[[Requires][`A` is an /Allocator/]]
110[[Effects]
111[Constructs each `i`-th element in order by calling
112`std::allocator_traits<A>::construct(a, &p[i], l[i % m])`.]]
113[[Remarks]
114[If an exception is thrown destroys each already constructed `j`-th element in
115reverse order by calling `std::allocator_traits<A>::destroy(a, &p[j])`.]]]]]
116[[`template<class A, class T, class I> void alloc_construct_n(A& a, T* p,
117std::size_t n, I begin);`]
118[[variablelist
119[[Requires]
120[[itemized_list
121[`A` is an /Allocator/][`I` is an /InputIterator/]]]]
122[[Effects]
123[Constructs each `i`-th element in order by calling
124`std::allocator_traits<A>::construct(a, &p[i], *begin++])`.]]
125[[Remarks]
126[If an exception is thrown destroys each already constructed `j`-th element in
127reverse order by calling `std::allocator_traits<A>::destroy(a, &p[j])`.]]]]]]
128
129[endsect]
130
131[endsect]
132
133[section Compatibility]
134
135When `BOOST_NO_CXX11_ALLOCATOR` is defined, and the C++11 allocator model is
136not supported, these functions invoke constructors and destructors directly
137without going through the supplied allocator.
138
139[endsect]
140
141[section Acknowledgments]
142
143Glen Fernandes originally implemented this functionality in Boost.Smart_Ptr and
144later moved these functions to Boost.Core for use in other Boost libraries,
145such as Boost.Multi_Array and Boost.Histogram.
146
147[endsect]
148
149[endsect]
150