1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Stack allocation</title> 5<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../index.html" title="Chapter 1. Fiber"> 8<link rel="up" href="../index.html" title="Chapter 1. Fiber"> 9<link rel="prev" href="scheduling.html" title="Scheduling"> 10<link rel="next" href="stack/valgrind.html" title="Support for valgrind"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> 15<td align="center"><a href="../../../../../index.html">Home</a></td> 16<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> 17<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 18<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 19<td align="center"><a href="../../../../../more/index.htm">More</a></td> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="scheduling.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="stack/valgrind.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 27<a name="fiber.stack"></a><a name="stack"></a><a class="link" href="stack.html" title="Stack allocation">Stack allocation</a> 28</h2></div></div></div> 29<div class="toc"><dl class="toc"> 30<dt><span class="section"><a href="stack/valgrind.html">Support for valgrind</a></span></dt> 31<dt><span class="section"><a href="stack/sanitizers.html">Support for sanitizers</a></span></dt> 32</dl></div> 33<p> 34 A <a class="link" href="fiber_mgmt/fiber.html#class_fiber"><code class="computeroutput">fiber</code></a> uses internally an __econtext__ which manages a set of registers 35 and a stack. The memory used by the stack is allocated/deallocated via a <span class="emphasis"><em>stack_allocator</em></span> 36 which is required to model a <a class="link" href="stack.html#stack_allocator_concept"><span class="emphasis"><em>stack-allocator 37 concept</em></span></a>. 38 </p> 39<p> 40 A <span class="emphasis"><em>stack_allocator</em></span> can be passed to <a class="link" href="fiber_mgmt/fiber.html#fiber_fiber"><code class="computeroutput"><span class="identifier">fiber</span><span class="special">::</span><span class="identifier">fiber</span><span class="special">()</span></code></a> or to <a class="link" href="synchronization/futures/future.html#fibers_async"><code class="computeroutput">fibers::async()</code></a>. 41 </p> 42<a name="stack_allocator_concept"></a><h4> 43<a name="fiber.stack.h0"></a> 44 <span class="phrase"><a name="fiber.stack.stack_allocator_concept"></a></span><a class="link" href="stack.html#fiber.stack.stack_allocator_concept">stack-allocator 45 concept</a> 46 </h4> 47<p> 48 A <span class="emphasis"><em>stack_allocator</em></span> must satisfy the <span class="emphasis"><em>stack-allocator 49 concept</em></span> requirements shown in the following table, in which <code class="computeroutput"><span class="identifier">a</span></code> is an object of a <span class="emphasis"><em>stack_allocator</em></span> 50 type, <code class="computeroutput"><span class="identifier">sctx</span></code> is a <a href="http://www.boost.org/doc/libs/release/libs/context/doc/html/context/stack/stack_context.html" target="_top"><code class="computeroutput"><span class="identifier">stack_context</span></code></a>, and <code class="computeroutput"><span class="identifier">size</span></code> is a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code>: 51 </p> 52<div class="informaltable"><table class="table"> 53<colgroup> 54<col> 55<col> 56<col> 57</colgroup> 58<thead><tr> 59<th> 60 <p> 61 expression 62 </p> 63 </th> 64<th> 65 <p> 66 return type 67 </p> 68 </th> 69<th> 70 <p> 71 notes 72 </p> 73 </th> 74</tr></thead> 75<tbody> 76<tr> 77<td> 78 <p> 79 <code class="computeroutput"><span class="identifier">a</span><span class="special">(</span><span class="identifier">size</span><span class="special">)</span></code> 80 </p> 81 </td> 82<td> 83 </td> 84<td> 85 <p> 86 creates a stack allocator 87 </p> 88 </td> 89</tr> 90<tr> 91<td> 92 <p> 93 <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">allocate</span><span class="special">()</span></code> 94 </p> 95 </td> 96<td> 97 <p> 98 <a href="http://www.boost.org/doc/libs/release/libs/context/doc/html/context/stack/stack_context.html" target="_top"><code class="computeroutput"><span class="identifier">stack_context</span></code></a> 99 </p> 100 </td> 101<td> 102 <p> 103 creates a stack 104 </p> 105 </td> 106</tr> 107<tr> 108<td> 109 <p> 110 <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">deallocate</span><span class="special">(</span> 111 <span class="identifier">sctx</span><span class="special">)</span></code> 112 </p> 113 </td> 114<td> 115 <p> 116 <code class="computeroutput"><span class="keyword">void</span></code> 117 </p> 118 </td> 119<td> 120 <p> 121 deallocates the stack created by <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">allocate</span><span class="special">()</span></code> 122 </p> 123 </td> 124</tr> 125</tbody> 126</table></div> 127<div class="important"><table border="0" summary="Important"> 128<tr> 129<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td> 130<th align="left">Important</th> 131</tr> 132<tr><td align="left" valign="top"><p> 133 The implementation of <code class="computeroutput"><span class="identifier">allocate</span><span class="special">()</span></code> might include logic to protect against 134 exceeding the context's available stack size rather than leaving it as undefined 135 behaviour. 136 </p></td></tr> 137</table></div> 138<div class="important"><table border="0" summary="Important"> 139<tr> 140<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td> 141<th align="left">Important</th> 142</tr> 143<tr><td align="left" valign="top"><p> 144 Calling <code class="computeroutput"><span class="identifier">deallocate</span><span class="special">()</span></code> 145 with a <a href="http://www.boost.org/doc/libs/release/libs/context/doc/html/context/stack/stack_context.html" target="_top"><code class="computeroutput"><span class="identifier">stack_context</span></code></a> not obtained from 146 <code class="computeroutput"><span class="identifier">allocate</span><span class="special">()</span></code> 147 results in undefined behaviour. 148 </p></td></tr> 149</table></div> 150<div class="note"><table border="0" summary="Note"> 151<tr> 152<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 153<th align="left">Note</th> 154</tr> 155<tr><td align="left" valign="top"><p> 156 The memory for the stack is not required to be aligned; alignment takes place 157 inside __econtext__. 158 </p></td></tr> 159</table></div> 160<p> 161 See also <a href="http://www.boost.org/doc/libs/release/libs/context/doc/html/context/stack.html" target="_top">Boost.Context 162 stack allocation</a>. In particular, <code class="computeroutput"><span class="identifier">traits_type</span></code> 163 methods are as described for <a href="http://www.boost.org/doc/libs/release/libs/context/doc/html/context/stack/stack_traits.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">context</span><span class="special">::</span><span class="identifier">stack_traits</span></code></a>. 164 </p> 165<p> 166 </p> 167<h5> 168<a name="class_protected_fixedsize_stack_bridgehead"></a> 169 <span class="phrase"><a name="class_protected_fixedsize_stack"></a></span> 170 <a class="link" href="stack.html#class_protected_fixedsize_stack">Class 171 <code class="computeroutput">protected_fixedsize_stack</code></a> 172</h5> 173<p> 174 </p> 175<p> 176 <span class="bold"><strong>Boost.Fiber</strong></span> provides the class <a class="link" href="stack.html#class_protected_fixedsize_stack"><code class="computeroutput">protected_fixedsize_stack</code></a> which 177 models the <a class="link" href="stack.html#stack_allocator_concept"><span class="emphasis"><em>stack-allocator 178 concept</em></span></a>. It appends a guard page at the end of each stack 179 to protect against exceeding the stack. If the guard page is accessed (read 180 or write operation) a segmentation fault/access violation is generated by the 181 operating system. 182 </p> 183<div class="important"><table border="0" summary="Important"> 184<tr> 185<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td> 186<th align="left">Important</th> 187</tr> 188<tr><td align="left" valign="top"><p> 189 Using <a class="link" href="stack.html#class_protected_fixedsize_stack"><code class="computeroutput">protected_fixedsize_stack</code></a> is expensive. 190 Launching a new fiber with a stack of this type incurs the overhead of setting 191 the memory protection; once allocated, this stack is just as efficient to 192 use as <a class="link" href="stack.html#class_fixedsize_stack"><code class="computeroutput">fixedsize_stack</code></a>. 193 </p></td></tr> 194</table></div> 195<div class="note"><table border="0" summary="Note"> 196<tr> 197<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 198<th align="left">Note</th> 199</tr> 200<tr><td align="left" valign="top"><p> 201 The appended <code class="computeroutput"><span class="identifier">guard</span> <span class="identifier">page</span></code> 202 is <span class="bold"><strong>not</strong></span> mapped to physical memory, only virtual 203 addresses are used. 204 </p></td></tr> 205</table></div> 206<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">fiber</span><span class="special">/</span><span class="identifier">protected_fixedsize</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 207 208<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> 209<span class="keyword">namespace</span> <span class="identifier">fibers</span> <span class="special">{</span> 210 211<span class="keyword">struct</span> <span class="identifier">protected_fixedsize</span> <span class="special">{</span> 212 <span class="identifier">protected_fixesize</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">size</span> <span class="special">=</span> <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">default_size</span><span class="special">());</span> 213 214 <span class="identifier">stack_context</span> <span class="identifier">allocate</span><span class="special">();</span> 215 216 <span class="keyword">void</span> <span class="identifier">deallocate</span><span class="special">(</span> <span class="identifier">stack_context</span> <span class="special">&);</span> 217<span class="special">}</span> 218 219<span class="special">}}</span> 220</pre> 221<p> 222 </p> 223<h5> 224<a name="protected_fixedsize_allocate_bridgehead"></a> 225 <span class="phrase"><a name="protected_fixedsize_allocate"></a></span> 226 <a class="link" href="stack.html#protected_fixedsize_allocate">Member 227 function <code class="computeroutput">allocate</code>()</a> 228</h5> 229<p> 230 </p> 231<pre class="programlisting"><span class="identifier">stack_context</span> <span class="identifier">allocate</span><span class="special">();</span> 232</pre> 233<div class="variablelist"> 234<p class="title"><b></b></p> 235<dl class="variablelist"> 236<dt><span class="term">Preconditions:</span></dt> 237<dd><p> 238 <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">minimum_size</span><span class="special">()</span> 239 <span class="special"><=</span> <span class="identifier">size</span></code> 240 and <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">is_unbounded</span><span class="special">()</span> 241 <span class="special">||</span> <span class="special">(</span> 242 <span class="identifier">size</span> <span class="special"><=</span> 243 <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">maximum_size</span><span class="special">()</span> 244 <span class="special">)</span></code>. 245 </p></dd> 246<dt><span class="term">Effects:</span></dt> 247<dd><p> 248 Allocates memory of at least <code class="computeroutput"><span class="identifier">size</span></code> 249 bytes and stores a pointer to the stack and its actual size in <code class="computeroutput"><span class="identifier">sctx</span></code>. Depending on the architecture 250 (the stack grows downwards/upwards) the stored address is the highest/lowest 251 address of the stack. 252 </p></dd> 253</dl> 254</div> 255<p> 256 </p> 257<h5> 258<a name="protected_fixesize_deallocate_bridgehead"></a> 259 <span class="phrase"><a name="protected_fixesize_deallocate"></a></span> 260 <a class="link" href="stack.html#protected_fixesize_deallocate">Member 261 function <code class="computeroutput">deallocate</code>()</a> 262</h5> 263<p> 264 </p> 265<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">deallocate</span><span class="special">(</span> <span class="identifier">stack_context</span> <span class="special">&</span> <span class="identifier">sctx</span><span class="special">);</span> 266</pre> 267<div class="variablelist"> 268<p class="title"><b></b></p> 269<dl class="variablelist"> 270<dt><span class="term">Preconditions:</span></dt> 271<dd><p> 272 <code class="computeroutput"><span class="identifier">sctx</span><span class="special">.</span><span class="identifier">sp</span></code> is valid, <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">minimum_size</span><span class="special">()</span> <span class="special"><=</span> <span class="identifier">sctx</span><span class="special">.</span><span class="identifier">size</span></code> and <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">is_unbounded</span><span class="special">()</span> <span class="special">||</span> <span class="special">(</span> <span class="identifier">sctx</span><span class="special">.</span><span class="identifier">size</span> <span class="special"><=</span> <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">maximum_size</span><span class="special">()</span> <span class="special">)</span></code>. 273 </p></dd> 274<dt><span class="term">Effects:</span></dt> 275<dd><p> 276 Deallocates the stack space. 277 </p></dd> 278</dl> 279</div> 280<p> 281 </p> 282<h5> 283<a name="class_pooled_fixedsize_stack_bridgehead"></a> 284 <span class="phrase"><a name="class_pooled_fixedsize_stack"></a></span> 285 <a class="link" href="stack.html#class_pooled_fixedsize_stack">Class 286 <code class="computeroutput">pooled_fixedsize_stack</code></a> 287</h5> 288<p> 289 </p> 290<p> 291 <span class="bold"><strong>Boost.Fiber</strong></span> provides the class <a class="link" href="stack.html#class_pooled_fixedsize_stack"><code class="computeroutput">pooled_fixedsize_stack</code></a> which 292 models the <a class="link" href="stack.html#stack_allocator_concept"><span class="emphasis"><em>stack-allocator 293 concept</em></span></a>. In contrast to <a class="link" href="stack.html#class_protected_fixedsize_stack"><code class="computeroutput">protected_fixedsize_stack</code></a> it 294 does not append a guard page at the end of each stack. The memory is managed 295 internally by <a href="http://www.boost.org/doc/libs/release/libs/pool/doc/html/boost/pool.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">pool</span><span class="special"><></span></code></a>. 296 </p> 297<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">fiber</span><span class="special">/</span><span class="identifier">pooled_fixedsize_stack</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 298 299<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> 300<span class="keyword">namespace</span> <span class="identifier">fibers</span> <span class="special">{</span> 301 302<span class="keyword">struct</span> <span class="identifier">pooled_fixedsize_stack</span> <span class="special">{</span> 303 <span class="identifier">pooled_fixedsize_stack</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">stack_size</span> <span class="special">=</span> <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">default_size</span><span class="special">(),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">next_size</span> <span class="special">=</span> <span class="number">32</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">max_size</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span> 304 305 <span class="identifier">stack_context</span> <span class="identifier">allocate</span><span class="special">();</span> 306 307 <span class="keyword">void</span> <span class="identifier">deallocate</span><span class="special">(</span> <span class="identifier">stack_context</span> <span class="special">&);</span> 308<span class="special">}</span> 309 310<span class="special">}}</span> 311</pre> 312<p> 313 </p> 314<h5> 315<a name="pooled_fixedsize_bridgehead"></a> 316 <span class="phrase"><a name="pooled_fixedsize"></a></span> 317 <a class="link" href="stack.html#pooled_fixedsize">Constructor</a> 318</h5> 319<p> 320 </p> 321<pre class="programlisting"><span class="identifier">pooled_fixedsize_stack</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">stack_size</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">next_size</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">max_size</span><span class="special">);</span> 322</pre> 323<div class="variablelist"> 324<p class="title"><b></b></p> 325<dl class="variablelist"> 326<dt><span class="term">Preconditions:</span></dt> 327<dd><p> 328 <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">is_unbounded</span><span class="special">()</span> 329 <span class="special">||</span> <span class="special">(</span> 330 <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">maximum_size</span><span class="special">()</span> 331 <span class="special">>=</span> <span class="identifier">stack_size</span><span class="special">)</span></code> and <code class="computeroutput"><span class="number">0</span> 332 <span class="special"><</span> <span class="identifier">next_size</span></code>. 333 </p></dd> 334<dt><span class="term">Effects:</span></dt> 335<dd><p> 336 Allocates memory of at least <code class="computeroutput"><span class="identifier">stack_size</span></code> 337 bytes and stores a pointer to the stack and its actual size in <code class="computeroutput"><span class="identifier">sctx</span></code>. Depending on the architecture 338 (the stack grows downwards/upwards) the stored address is the highest/lowest 339 address of the stack. Argument <code class="computeroutput"><span class="identifier">next_size</span></code> 340 determines the number of stacks to request from the system the first 341 time that <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> 342 needs to allocate system memory. The third argument <code class="computeroutput"><span class="identifier">max_size</span></code> 343 controls how much memory might be allocated for stacks — a value of zero 344 means no upper limit. 345 </p></dd> 346</dl> 347</div> 348<p> 349 </p> 350<h5> 351<a name="pooled_fixedsize_allocate_bridgehead"></a> 352 <span class="phrase"><a name="pooled_fixedsize_allocate"></a></span> 353 <a class="link" href="stack.html#pooled_fixedsize_allocate">Member 354 function <code class="computeroutput">allocate</code>()</a> 355</h5> 356<p> 357 </p> 358<pre class="programlisting"><span class="identifier">stack_context</span> <span class="identifier">allocate</span><span class="special">();</span> 359</pre> 360<div class="variablelist"> 361<p class="title"><b></b></p> 362<dl class="variablelist"> 363<dt><span class="term">Preconditions:</span></dt> 364<dd><p> 365 <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">is_unbounded</span><span class="special">()</span> 366 <span class="special">||</span> <span class="special">(</span> 367 <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">maximum_size</span><span class="special">()</span> 368 <span class="special">>=</span> <span class="identifier">stack_size</span><span class="special">)</span></code>. 369 </p></dd> 370<dt><span class="term">Effects:</span></dt> 371<dd><p> 372 Allocates memory of at least <code class="computeroutput"><span class="identifier">stack_size</span></code> 373 bytes and stores a pointer to the stack and its actual size in <code class="computeroutput"><span class="identifier">sctx</span></code>. Depending on the architecture 374 (the stack grows downwards/upwards) the stored address is the highest/lowest 375 address of the stack. 376 </p></dd> 377</dl> 378</div> 379<p> 380 </p> 381<h5> 382<a name="pooled_fixesize_deallocate_bridgehead"></a> 383 <span class="phrase"><a name="pooled_fixesize_deallocate"></a></span> 384 <a class="link" href="stack.html#pooled_fixesize_deallocate">Member 385 function <code class="computeroutput">deallocate</code>()</a> 386</h5> 387<p> 388 </p> 389<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">deallocate</span><span class="special">(</span> <span class="identifier">stack_context</span> <span class="special">&</span> <span class="identifier">sctx</span><span class="special">);</span> 390</pre> 391<div class="variablelist"> 392<p class="title"><b></b></p> 393<dl class="variablelist"> 394<dt><span class="term">Preconditions:</span></dt> 395<dd><p> 396 <code class="computeroutput"><span class="identifier">sctx</span><span class="special">.</span><span class="identifier">sp</span></code> is valid, <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">is_unbounded</span><span class="special">()</span> <span class="special">||</span> <span class="special">(</span> <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">maximum_size</span><span class="special">()</span> <span class="special">>=</span> <span class="identifier">sctx</span><span class="special">.</span><span class="identifier">size</span><span class="special">)</span></code>. 397 </p></dd> 398<dt><span class="term">Effects:</span></dt> 399<dd><p> 400 Deallocates the stack space. 401 </p></dd> 402</dl> 403</div> 404<div class="note"><table border="0" summary="Note"> 405<tr> 406<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 407<th align="left">Note</th> 408</tr> 409<tr><td align="left" valign="top"><p> 410 This stack allocator is not thread safe. 411 </p></td></tr> 412</table></div> 413<p> 414 </p> 415<h5> 416<a name="class_fixedsize_stack_bridgehead"></a> 417 <span class="phrase"><a name="class_fixedsize_stack"></a></span> 418 <a class="link" href="stack.html#class_fixedsize_stack">Class 419 <code class="computeroutput">fixedsize_stack</code></a> 420</h5> 421<p> 422 </p> 423<p> 424 <span class="bold"><strong>Boost.Fiber</strong></span> provides the class <a class="link" href="stack.html#class_fixedsize_stack"><code class="computeroutput">fixedsize_stack</code></a> which 425 models the <a class="link" href="stack.html#stack_allocator_concept"><span class="emphasis"><em>stack-allocator 426 concept</em></span></a>. In contrast to <a class="link" href="stack.html#class_protected_fixedsize_stack"><code class="computeroutput">protected_fixedsize_stack</code></a> it 427 does not append a guard page at the end of each stack. The memory is simply 428 managed by <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">malloc</span><span class="special">()</span></code> 429 and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">free</span><span class="special">()</span></code>. 430 </p> 431<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">context</span><span class="special">/</span><span class="identifier">fixedsize_stack</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 432 433<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> 434<span class="keyword">namespace</span> <span class="identifier">fibers</span> <span class="special">{</span> 435 436<span class="keyword">struct</span> <span class="identifier">fixedsize_stack</span> <span class="special">{</span> 437 <span class="identifier">fixedsize_stack</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">size</span> <span class="special">=</span> <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">default_size</span><span class="special">());</span> 438 439 <span class="identifier">stack_context</span> <span class="identifier">allocate</span><span class="special">();</span> 440 441 <span class="keyword">void</span> <span class="identifier">deallocate</span><span class="special">(</span> <span class="identifier">stack_context</span> <span class="special">&);</span> 442<span class="special">}</span> 443 444<span class="special">}}</span> 445</pre> 446<p> 447 </p> 448<h5> 449<a name="fixedsize_allocate_bridgehead"></a> 450 <span class="phrase"><a name="fixedsize_allocate"></a></span> 451 <a class="link" href="stack.html#fixedsize_allocate">Member function 452 <code class="computeroutput">allocate</code>()</a> 453</h5> 454<p> 455 </p> 456<pre class="programlisting"><span class="identifier">stack_context</span> <span class="identifier">allocate</span><span class="special">();</span> 457</pre> 458<div class="variablelist"> 459<p class="title"><b></b></p> 460<dl class="variablelist"> 461<dt><span class="term">Preconditions:</span></dt> 462<dd><p> 463 <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">minimum_size</span><span class="special">()</span> 464 <span class="special"><=</span> <span class="identifier">size</span></code> 465 and <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">is_unbounded</span><span class="special">()</span> 466 <span class="special">||</span> <span class="special">(</span> 467 <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">maximum_size</span><span class="special">()</span> 468 <span class="special">>=</span> <span class="identifier">size</span><span class="special">)</span></code>. 469 </p></dd> 470<dt><span class="term">Effects:</span></dt> 471<dd><p> 472 Allocates memory of at least <code class="computeroutput"><span class="identifier">size</span></code> 473 bytes and stores a pointer to the stack and its actual size in <code class="computeroutput"><span class="identifier">sctx</span></code>. Depending on the architecture 474 (the stack grows downwards/upwards) the stored address is the highest/lowest 475 address of the stack. 476 </p></dd> 477</dl> 478</div> 479<p> 480 </p> 481<h5> 482<a name="fixesize_deallocate_bridgehead"></a> 483 <span class="phrase"><a name="fixesize_deallocate"></a></span> 484 <a class="link" href="stack.html#fixesize_deallocate">Member 485 function <code class="computeroutput">deallocate</code>()</a> 486</h5> 487<p> 488 </p> 489<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">deallocate</span><span class="special">(</span> <span class="identifier">stack_context</span> <span class="special">&</span> <span class="identifier">sctx</span><span class="special">);</span> 490</pre> 491<div class="variablelist"> 492<p class="title"><b></b></p> 493<dl class="variablelist"> 494<dt><span class="term">Preconditions:</span></dt> 495<dd><p> 496 <code class="computeroutput"><span class="identifier">sctx</span><span class="special">.</span><span class="identifier">sp</span></code> is valid, <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">minimum_size</span><span class="special">()</span> <span class="special"><=</span> <span class="identifier">sctx</span><span class="special">.</span><span class="identifier">size</span></code> and <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">is_unbounded</span><span class="special">()</span> <span class="special">||</span> <span class="special">(</span> <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">maximum_size</span><span class="special">()</span> <span class="special">>=</span> <span class="identifier">sctx</span><span class="special">.</span><span class="identifier">size</span><span class="special">)</span></code>. 497 </p></dd> 498<dt><span class="term">Effects:</span></dt> 499<dd><p> 500 Deallocates the stack space. 501 </p></dd> 502</dl> 503</div> 504<p> 505 <a name="segmented"></a></p> 506<h5> 507<a name="class_segmented_stack_bridgehead"></a> 508 <span class="phrase"><a name="class_segmented_stack"></a></span> 509 <a class="link" href="stack.html#class_segmented_stack">Class 510 <code class="computeroutput">segmented_stack</code></a> 511</h5> 512<p> 513 </p> 514<p> 515 <span class="bold"><strong>Boost.Fiber</strong></span> supports usage of a <a class="link" href="stack.html#class_segmented_stack"><code class="computeroutput">segmented_stack</code></a>, 516 i.e. the stack grows on demand. The fiber is created with a minimal stack size 517 which will be increased as required. Class <a class="link" href="stack.html#class_segmented_stack"><code class="computeroutput">segmented_stack</code></a> models 518 the <a class="link" href="stack.html#stack_allocator_concept"><span class="emphasis"><em>stack-allocator concept</em></span></a>. 519 In contrast to <a class="link" href="stack.html#class_protected_fixedsize_stack"><code class="computeroutput">protected_fixedsize_stack</code></a> and 520 <a class="link" href="stack.html#class_fixedsize_stack"><code class="computeroutput">fixedsize_stack</code></a> it creates a stack which grows on demand. 521 </p> 522<div class="note"><table border="0" summary="Note"> 523<tr> 524<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 525<th align="left">Note</th> 526</tr> 527<tr><td align="left" valign="top"><p> 528 Segmented stacks are currently only supported by <span class="bold"><strong>gcc</strong></span> 529 from version <span class="bold"><strong>4.7</strong></span> and <span class="bold"><strong>clang</strong></span> 530 from version <span class="bold"><strong>3.4</strong></span> onwards. In order to use 531 a <a class="link" href="stack.html#class_segmented_stack"><code class="computeroutput">segmented_stack</code></a> <span class="bold"><strong>Boost.Fiber</strong></span> 532 must be built with property <code class="computeroutput"><span class="identifier">segmented</span><span class="special">-</span><span class="identifier">stacks</span></code>, 533 e.g. <span class="bold"><strong>toolset=gcc segmented-stacks=on</strong></span> and 534 applying BOOST_USE_SEGMENTED_STACKS at b2/bjam command line. 535 </p></td></tr> 536</table></div> 537<div class="note"><table border="0" summary="Note"> 538<tr> 539<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 540<th align="left">Note</th> 541</tr> 542<tr><td align="left" valign="top"><p> 543 Segmented stacks can only be used with callcc() using property <code class="computeroutput"><span class="identifier">context</span><span class="special">-</span><span class="identifier">impl</span><span class="special">=</span><span class="identifier">ucontext</span></code>. 544 </p></td></tr> 545</table></div> 546<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">fiber</span><span class="special">/</span><span class="identifier">segmented_stack</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 547 548<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> 549<span class="keyword">namespace</span> <span class="identifier">fibers</span> <span class="special">{</span> 550 551<span class="keyword">struct</span> <span class="identifier">segmented_stack</span> <span class="special">{</span> 552 <span class="identifier">segmented_stack</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">stack_size</span> <span class="special">=</span> <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">default_size</span><span class="special">());</span> 553 554 <span class="identifier">stack_context</span> <span class="identifier">allocate</span><span class="special">();</span> 555 556 <span class="keyword">void</span> <span class="identifier">deallocate</span><span class="special">(</span> <span class="identifier">stack_context</span> <span class="special">&);</span> 557<span class="special">}</span> 558 559<span class="special">}}</span> 560</pre> 561<p> 562 </p> 563<h5> 564<a name="segmented_allocate_bridgehead"></a> 565 <span class="phrase"><a name="segmented_allocate"></a></span> 566 <a class="link" href="stack.html#segmented_allocate">Member function 567 <code class="computeroutput">allocate</code>()</a> 568</h5> 569<p> 570 </p> 571<pre class="programlisting"><span class="identifier">stack_context</span> <span class="identifier">allocate</span><span class="special">();</span> 572</pre> 573<div class="variablelist"> 574<p class="title"><b></b></p> 575<dl class="variablelist"> 576<dt><span class="term">Preconditions:</span></dt> 577<dd><p> 578 <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">minimum_size</span><span class="special">()</span> 579 <span class="special"><=</span> <span class="identifier">size</span></code> 580 and <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">is_unbounded</span><span class="special">()</span> 581 <span class="special">||</span> <span class="special">(</span> 582 <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">maximum_size</span><span class="special">()</span> 583 <span class="special">>=</span> <span class="identifier">size</span><span class="special">)</span></code>. 584 </p></dd> 585<dt><span class="term">Effects:</span></dt> 586<dd><p> 587 Allocates memory of at least <code class="computeroutput"><span class="identifier">size</span></code> 588 bytes and stores a pointer to the stack and its actual size in <code class="computeroutput"><span class="identifier">sctx</span></code>. Depending on the architecture 589 (the stack grows downwards/upwards) the stored address is the highest/lowest 590 address of the stack. 591 </p></dd> 592</dl> 593</div> 594<p> 595 </p> 596<h5> 597<a name="segmented_deallocate_bridgehead"></a> 598 <span class="phrase"><a name="segmented_deallocate"></a></span> 599 <a class="link" href="stack.html#segmented_deallocate">Member 600 function <code class="computeroutput">deallocate</code>()</a> 601</h5> 602<p> 603 </p> 604<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">deallocate</span><span class="special">(</span> <span class="identifier">stack_context</span> <span class="special">&</span> <span class="identifier">sctx</span><span class="special">);</span> 605</pre> 606<div class="variablelist"> 607<p class="title"><b></b></p> 608<dl class="variablelist"> 609<dt><span class="term">Preconditions:</span></dt> 610<dd><p> 611 <code class="computeroutput"><span class="identifier">sctx</span><span class="special">.</span><span class="identifier">sp</span></code> is valid, <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">minimum_size</span><span class="special">()</span> <span class="special"><=</span> <span class="identifier">sctx</span><span class="special">.</span><span class="identifier">size</span></code> and <code class="computeroutput"><span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">is_unbounded</span><span class="special">()</span> <span class="special">||</span> <span class="special">(</span> <span class="identifier">traits_type</span><span class="special">::</span><span class="identifier">maximum_size</span><span class="special">()</span> <span class="special">>=</span> <span class="identifier">sctx</span><span class="special">.</span><span class="identifier">size</span><span class="special">)</span></code>. 612 </p></dd> 613<dt><span class="term">Effects:</span></dt> 614<dd><p> 615 Deallocates the stack space. 616 </p></dd> 617</dl> 618</div> 619<div class="note"><table border="0" summary="Note"> 620<tr> 621<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 622<th align="left">Note</th> 623</tr> 624<tr><td align="left" valign="top"><p> 625 If the library is compiled for segmented stacks, <a class="link" href="stack.html#class_segmented_stack"><code class="computeroutput">segmented_stack</code></a> is 626 the only available stack allocator. 627 </p></td></tr> 628</table></div> 629</div> 630<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 631<td align="left"></td> 632<td align="right"><div class="copyright-footer">Copyright © 2013 Oliver Kowalke<p> 633 Distributed under the Boost Software License, Version 1.0. (See accompanying 634 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 635 </p> 636</div></td> 637</tr></table> 638<hr> 639<div class="spirit-nav"> 640<a accesskey="p" href="scheduling.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="stack/valgrind.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 641</div> 642</body> 643</html> 644
