ceph/src/boost/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 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]