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