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