libs/context/doc/stack.qbk

   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 Depending on the architecture `allocate()` stores an address from the
  47 top of the stack (growing downwards) or the bottom of the stack (growing
  48 upwards).]
  49
  50
  51 [section:protected_fixedsize Class ['protected_fixedsize]]
  52
  53 __boost_context__ provides the class __protected_fixedsize__ which models
  54 the __stack_allocator_concept__.
  55 It appends a guard page at the end of each stack to protect against exceeding
  56 the stack. If the guard page is accessed (read or write operation) a
  57 segmentation fault/access violation is generated by the operating system.
  58
  59 [important Using __protected_fixedsize__ is expensive. That is, launching a
  60 new coroutine with a new stack is expensive; the allocated stack is just as
  61 efficient to use as any other stack.]
  62
  63 [note The appended `guard page` is [*not] mapped to physical memory, only
  64 virtual 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
  86 to the stack and its actual size in `sctx`. Depending
  87 on the architecture (the stack grows downwards/upwards) the stored address is
  88 the 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
 104 the __stack_allocator_concept__.
 105 In contrast to __protected_fixedsize__ it does not append a guard page at the
 106 end 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)`
 127 and `0 < nest_size`.]]
 128 [[Effects:] [Allocates memory of at least `stack_size` Bytes and stores a pointer to
 129 the stack and its actual size in `sctx`. Depending on the architecture (the
 130 stack grows downwards/upwards) the stored address is the highest/lowest
 131 address of the stack. Argument `next_size` determines the number of stacks to
 132 request from the system the first time that `*this` needs to allocate system
 133 memory. The third argument `max_size` controls how many memory might be
 134 allocated 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
 141 the stack and its actual size in `sctx`. Depending on the architecture (the
 142 stack grows downwards/upwards) the stored address is the highest/lowest
 143 address 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
 159 the __stack_allocator_concept__.
 160 In contrast to __protected_fixedsize__ it does not append a guard page at the
 161 end 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
 184 the stack and its actual size in `sctx`. Depending on the architecture (the
 185 stack grows downwards/upwards) the stored address is the highest/lowest
 186 address 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
 203 the stack grows on demand. The coroutine is created with a minimal stack size
 204 and will be increased as required.
 205 Class __segmented__ models the __stack_allocator_concept__.
 206 In contrast to __protected_fixedsize__ and __fixedsize__ it creates a
 207 stack 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
 212 property `segmented-stacks`, e.g. [*toolset=gcc segmented-stacks=on] and
 213 applying `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
 238 the stack and its actual size in `sctx`. Depending on the architecture (the
 239 stack grows downwards/upwards) the stored address is the highest/lowest
 240 address 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
 251 available 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
 259 properites defined by the enironment. Stack allocators use __stack_traits__ to
 260 allocate 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
 280 a 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.
 293 If 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
 301 environment (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
 309 environment.]]
 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
 320 the stack pointer and the size of the stack.
 321 In case of a __segmented__, __stack_context__ contains some extra control
 322 structures.
 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
 347 Running programs that switch stacks under valgrind causes problems.
 348 Property (b2 command-line) `valgrind=on` let valgrind treat the memory regions
 349 as stack space which suppresses the errors. Users must define `BOOST_USE_VALGRIND`
 350 before including any Boost.Context headers when linking against Boost binaries
 351 compiled with `valgrind=on`.
 352
 353 [endsect]
 354
 355
 356 [section:sanitizers Support for sanitizers]
 357
 358 Sanitizers (GCC/Clang) are confused by the stack switches.
 359 The library is required to be compiled with property (b2 command-line)
 360 `context-impl=ucontext` and compilers santizer options.
 361 Users must define `BOOST_USE_ASAN` before including any Boost.Context headers
 362 when linking against Boost binaries.
 363
 364 [endsect]
 365
 366
 367 [endsect]