]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/ |
2 | Copyright Oliver Kowalke 2014. | |
3 | Distributed under the Boost Software License, Version 1.0. | |
4 | (See accompanying file LICENSE_1_0.txt or copy at | |
5 | http://www.boost.org/LICENSE_1_0.txt | |
6 | ] | |
7 | ||
8 | [#stack] | |
9 | [section:stack Stack allocation] | |
10 | ||
11 | The memory used by the stack is allocated/deallocated via a __stack_allocator__ | |
12 | which is required to model a __stack_allocator_concept__. | |
13 | ||
14 | ||
15 | [heading __stack_allocator_concept__] | |
16 | A __stack_allocator__ must satisfy the __stack_allocator_concept__ requirements | |
17 | shown in the following table, in which `a` is an object of a | |
18 | __stack_allocator__ type, `sctx` is a `stack_context`, and `size` is a `std::size_t`: | |
19 | ||
20 | [table | |
21 | [[expression][return type][notes]] | |
22 | [ | |
23 | [`a(size)`] | |
24 | [] | |
25 | [creates a stack allocator] | |
26 | ] | |
27 | [ | |
28 | [`a.allocate()`] | |
29 | [`stack_context`] | |
30 | [creates a stack] | |
31 | ] | |
32 | [ | |
33 | [`a.deallocate( sctx)`] | |
34 | [`void`] | |
35 | [deallocates the stack created by `a.allocate()`] | |
36 | ] | |
37 | ] | |
38 | ||
39 | [important The implementation of `allocate()` might include logic to protect | |
40 | against exceeding the context's available stack size rather than leaving it as | |
41 | undefined behaviour.] | |
42 | ||
43 | [important Calling `deallocate()` with a `stack_context` not set by `allocate()` | |
44 | results in undefined behaviour.] | |
45 | ||
46 | [note The stack is not required to be aligned; alignment takes place inside | |
47 | __econtext__.] | |
48 | ||
49 | [note Depending on the architecture `allocate()` stores an address from the | |
50 | top of the stack (growing downwards) or the bottom of the stack (growing | |
51 | upwards).] | |
52 | ||
53 | ||
54 | [section:protected_fixedsize Class ['protected_fixedsize]] | |
55 | ||
56 | __boost_context__ provides the class __protected_fixedsize__ which models | |
57 | the __stack_allocator_concept__. | |
58 | It appends a guard page at the end of each stack to protect against exceeding | |
59 | the stack. If the guard page is accessed (read or write operation) a | |
60 | segmentation fault/access violation is generated by the operating system. | |
61 | ||
62 | [important Using __protected_fixedsize__ is expensive. That is, launching a | |
63 | new coroutine with a new stack is expensive; the allocated stack is just as | |
64 | efficient to use as any other stack.] | |
65 | ||
66 | [note The appended `guard page` is [*not] mapped to physical memory, only | |
67 | virtual addresses are used.] | |
68 | ||
69 | #include <boost/context/protected_fixedsize.hpp> | |
70 | ||
71 | template< typename traitsT > | |
72 | struct basic_protected_fixedsize { | |
73 | typedef traitT traits_type; | |
74 | ||
75 | basic_protected_fixesize(std::size_t size = traits_type::default_size()); | |
76 | ||
77 | stack_context allocate(); | |
78 | ||
79 | void deallocate( stack_context &); | |
80 | } | |
81 | ||
82 | typedef basic_protected_fixedsize< stack_traits > protected_fixedsize | |
83 | ||
84 | [heading `stack_context allocate()`] | |
85 | [variablelist | |
86 | [[Preconditions:] [`traits_type::minimum:size() <= size` and | |
87 | `! traits_type::is_unbounded() && ( traits_type::maximum:size() >= size)`.]] | |
88 | [[Effects:] [Allocates memory of at least `size` Bytes and stores a pointer | |
89 | to the stack and its actual size in `sctx`. Depending | |
90 | on the architecture (the stack grows downwards/upwards) the stored address is | |
91 | the highest/lowest address of the stack.]] | |
92 | ] | |
93 | ||
94 | [heading `void deallocate( stack_context & sctx)`] | |
95 | [variablelist | |
96 | [[Preconditions:] [`sctx.sp` is valid, `traits_type::minimum:size() <= sctx.size` and | |
97 | `! traits_type::is_unbounded() && ( traits_type::maximum:size() >= sctx.size)`.]] | |
98 | [[Effects:] [Deallocates the stack space.]] | |
99 | ] | |
100 | ||
101 | [endsect] | |
102 | ||
103 | ||
104 | [section:pooled_fixedsize Class ['pooled_fixedsize_stack]] | |
105 | ||
106 | __boost_context__ provides the class __pooled_fixedsize__ which models | |
107 | the __stack_allocator_concept__. | |
108 | In contrast to __protected_fixedsize__ it does not append a guard page at the | |
109 | end of each stack. The memory is managed internally by | |
110 | [@http://www.boost.org/doc/libs/release/libs/pool/doc/html/boost/pool.html `boost::pool<>`]. | |
111 | ||
112 | #include <boost/context/pooled_fixedsize_stack.hpp> | |
113 | ||
114 | template< typename traitsT > | |
115 | struct basic_pooled_fixedsize_stack { | |
116 | typedef traitT traits_type; | |
117 | ||
118 | basic_pooled_fixedsize_stack(std::size_t stack_size = traits_type::default_size(), std::size_t next_size = 32, std::size_t max_size = 0); | |
119 | ||
120 | stack_context allocate(); | |
121 | ||
122 | void deallocate( stack_context &); | |
123 | } | |
124 | ||
125 | typedef basic_pooled_fixedsize_stack< stack_traits > pooled_fixedsize_stack; | |
126 | ||
127 | [heading `basic_pooled_fixedsize_stack(std::size_t stack_size, std::size_t next_size, std::size_t max_size)`] | |
128 | [variablelist | |
129 | [[Preconditions:] [`! traits_type::is_unbounded() && ( traits_type::maximum:size() >= stack_size)` | |
130 | and `0 < nest_size`.]] | |
131 | [[Effects:] [Allocates memory of at least `stack_size` Bytes and stores a pointer to | |
132 | the stack and its actual size in `sctx`. Depending on the architecture (the | |
133 | stack grows downwards/upwards) the stored address is the highest/lowest | |
134 | address of the stack. Argument `next_size` determines the number of stacks to | |
135 | request from the system the first time that `*this` needs to allocate system | |
136 | memory. The third argument `max_size` controls how many memory might be | |
137 | allocated for stacks - a value of zero means no uper limit.]] | |
138 | ] | |
139 | ||
140 | [heading `stack_context allocate()`] | |
141 | [variablelist | |
142 | [[Preconditions:] [`! traits_type::is_unbounded() && ( traits_type::maximum:size() >= stack_size)`.]] | |
143 | [[Effects:] [Allocates memory of at least `stack_size` Bytes and stores a pointer to | |
144 | the stack and its actual size in `sctx`. Depending on the architecture (the | |
145 | stack grows downwards/upwards) the stored address is the highest/lowest | |
146 | address of the stack.]] | |
147 | ] | |
148 | ||
149 | [heading `void deallocate( stack_context & sctx)`] | |
150 | [variablelist | |
151 | [[Preconditions:] [`sctx.sp` is valid, | |
152 | `! traits_type::is_unbounded() && ( traits_type::maximum:size() >= sctx.size)`.]] | |
153 | [[Effects:] [Deallocates the stack space.]] | |
154 | ] | |
155 | ||
156 | [endsect] | |
157 | ||
158 | ||
159 | [section:fixedsize Class ['fixedsize_stack]] | |
160 | ||
161 | __boost_context__ provides the class __fixedsize__ which models | |
162 | the __stack_allocator_concept__. | |
163 | In contrast to __protected_fixedsize__ it does not append a guard page at the | |
164 | end of each stack. The memory is simply managed by `std::malloc()` and | |
165 | `std::free()`. | |
166 | ||
167 | #include <boost/context/fixedsize_stack.hpp> | |
168 | ||
169 | template< typename traitsT > | |
170 | struct basic_fixedsize_stack { | |
171 | typedef traitT traits_type; | |
172 | ||
173 | basic_fixesize_stack(std::size_t size = traits_type::default_size()); | |
174 | ||
175 | stack_context allocate(); | |
176 | ||
177 | void deallocate( stack_context &); | |
178 | } | |
179 | ||
180 | typedef basic_fixedsize_stack< stack_traits > fixedsize_stack; | |
181 | ||
182 | [heading `stack_context allocate()`] | |
183 | [variablelist | |
184 | [[Preconditions:] [`traits_type::minimum:size() <= size` and | |
185 | `! traits_type::is_unbounded() && ( traits_type::maximum:size() >= size)`.]] | |
186 | [[Effects:] [Allocates memory of at least `size` Bytes and stores a pointer to | |
187 | the stack and its actual size in `sctx`. Depending on the architecture (the | |
188 | stack grows downwards/upwards) the stored address is the highest/lowest | |
189 | address of the stack.]] | |
190 | ] | |
191 | ||
192 | [heading `void deallocate( stack_context & sctx)`] | |
193 | [variablelist | |
194 | [[Preconditions:] [`sctx.sp` is valid, `traits_type::minimum:size() <= sctx.size` and | |
195 | `! traits_type::is_unbounded() && ( traits_type::maximum:size() >= sctx.size)`.]] | |
196 | [[Effects:] [Deallocates the stack space.]] | |
197 | ] | |
198 | ||
199 | [endsect] | |
200 | ||
201 | ||
202 | [section:segmented Class ['segmented_stack]] | |
203 | ||
204 | __boost_context__ supports usage of a __segmented__, e. g. the size of | |
205 | the stack grows on demand. The coroutine is created with a minimal stack size | |
206 | and will be increased as required. | |
207 | Class __segmented__ models the __stack_allocator_concept__. | |
208 | In contrast to __protected_fixedsize__ and __fixedsize__ it creates a | |
209 | stack which grows on demand. | |
210 | ||
211 | [note Segmented stacks are currently only supported by [*gcc] from version | |
212 | [*4.7] [*clang] from version [*3.4] onwards. In order to use a | |
213 | __segmented_stack__ __boost_context__ must be built with | |
214 | property `segmented-stacks`, e.g. [*toolset=gcc segmented-stacks=on] at b2/bjam | |
215 | command line.] | |
216 | ||
217 | #include <boost/context/segmented_stack.hpp> | |
218 | ||
219 | template< typename traitsT > | |
220 | struct basic_segmented_stack { | |
221 | typedef traitT traits_type; | |
222 | ||
223 | basic_segmented_stack(std::size_t size = traits_type::default_size()); | |
224 | ||
225 | stack_context allocate(); | |
226 | ||
227 | void deallocate( stack_context &); | |
228 | } | |
229 | ||
230 | typedef basic_segmented_stack< stack_traits > segmented_stack; | |
231 | ||
232 | [heading `stack_context allocate()`] | |
233 | [variablelist | |
234 | [[Preconditions:] [`traits_type::minimum:size() <= size` and | |
235 | `! traits_type::is_unbounded() && ( traits_type::maximum:size() >= size)`.]] | |
236 | [[Effects:] [Allocates memory of at least `size` Bytes and stores a pointer to | |
237 | the stack and its actual size in `sctx`. Depending on the architecture (the | |
238 | stack grows downwards/upwards) the stored address is the highest/lowest | |
239 | address of the stack.]] | |
240 | ] | |
241 | ||
242 | [heading `void deallocate( stack_context & sctx)`] | |
243 | [variablelist | |
244 | [[Preconditions:] [`sctx.sp` is valid, `traits_type::minimum:size() <= sctx.size` and | |
245 | `! traits_type::is_unbounded() && ( traits_type::maximum:size() >= sctx.size)`.]] | |
246 | [[Effects:] [Deallocates the stack space.]] | |
247 | ] | |
248 | ||
249 | [note If the library is compiled for segmented stacks, __segmented_stack__ is the only | |
250 | available stack allocator.] | |
251 | ||
252 | [endsect] | |
253 | ||
254 | ||
255 | [section:stack_traits Class ['stack_traits]] | |
256 | ||
257 | ['stack_traits] models a __stack_traits__ providing a way to access certain | |
258 | properites defined by the enironment. Stack allocators use __stack_traits__ to | |
259 | allocate stacks. | |
260 | ||
261 | #include <boost/context/stack_traits.hpp> | |
262 | ||
263 | struct stack_traits { | |
264 | static bool is_unbounded() noexcept; | |
265 | ||
266 | static std::size_t page_size() noexcept; | |
267 | ||
268 | static std::size_t default_size() noexcept; | |
269 | ||
270 | static std::size_t minimum_size() noexcept; | |
271 | ||
272 | static std::size_t maximum_size() noexcept; | |
273 | } | |
274 | ||
275 | ||
276 | [heading `static bool is_unbounded()`] | |
277 | [variablelist | |
278 | [[Returns:] [Returns `true` if the environment defines no limit for the size of | |
279 | a stack.]] | |
280 | [[Throws:] [Nothing.]] | |
281 | ] | |
282 | ||
283 | [heading `static std::size_t page_size()`] | |
284 | [variablelist | |
285 | [[Returns:] [Returns the page size in bytes.]] | |
286 | [[Throws:] [Nothing.]] | |
287 | ] | |
288 | ||
289 | [heading `static std::size_t default_size()`] | |
290 | [variablelist | |
291 | [[Returns:] [Returns a default stack size, which may be platform specific. | |
292 | If the stack is unbounded then the present implementation returns the maximum of | |
293 | `64 kB` and `minimum_size()`.]] | |
294 | [[Throws:] [Nothing.]] | |
295 | ] | |
296 | ||
297 | [heading `static std::size_t minimum_size()`] | |
298 | [variablelist | |
299 | [[Returns:] [Returns the minimum size in bytes of stack defined by the | |
300 | environment (Win32 4kB/Win64 8kB, defined by rlimit on POSIX).]] | |
301 | [[Throws:] [Nothing.]] | |
302 | ] | |
303 | ||
304 | [heading `static std::size_t maximum_size()`] | |
305 | [variablelist | |
306 | [[Preconditions:] [`is_unbounded()` returns `false`.]] | |
307 | [[Returns:] [Returns the maximum size in bytes of stack defined by the | |
308 | environment.]] | |
309 | [[Throws:] [Nothing.]] | |
310 | ] | |
311 | ||
312 | ||
313 | [endsect] | |
314 | ||
315 | ||
316 | [section:stack_context Class ['stack_context]] | |
317 | ||
318 | __boost_context__ provides the class __stack_context__ which will contain | |
319 | the stack pointer and the size of the stack. | |
320 | In case of a __segmented__, __stack_context__ contains some extra control | |
321 | structures. | |
322 | ||
323 | struct stack_context { | |
324 | void * sp; | |
325 | std::size_t size; | |
326 | ||
327 | // might contain additional control structures | |
328 | // for segmented stacks | |
329 | } | |
330 | ||
331 | [heading `void * sp`] | |
332 | [variablelist | |
333 | [[Value:] [Pointer to the beginning of the stack.]] | |
334 | ] | |
335 | ||
336 | [heading `std::size_t size`] | |
337 | [variablelist | |
338 | [[Value:] [Actual size of the stack.]] | |
339 | ] | |
340 | ||
341 | [endsect] | |
342 | ||
343 | ||
344 | [section:valgrind Support for valgrind] | |
345 | ||
346 | Running programs that switch stacks under valgrind causes problems. | |
347 | Property (b2 command-line) `valgrind=on` let valgrind treat the memory regions | |
348 | as stack space which suppresses the errors. | |
349 | ||
350 | [endsect] | |
351 | ||
352 | ||
353 | [endsect] |