1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Fiber local storage</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="synchronization/futures/packaged_task.html" title="Template packaged_task<>"> 10<link rel="next" href="migration.html" title="Migrating fibers between threads"> 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="synchronization/futures/packaged_task.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="migration.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.fls"></a><a class="link" href="fls.html" title="Fiber local storage">Fiber local storage</a> 28</h2></div></div></div> 29<h4> 30<a name="fiber.fls.h0"></a> 31 <span class="phrase"><a name="fiber.fls.synopsis"></a></span><a class="link" href="fls.html#fiber.fls.synopsis">Synopsis</a> 32 </h4> 33<p> 34 Fiber local storage allows a separate instance of a given data item for each 35 fiber. 36 </p> 37<h4> 38<a name="fiber.fls.h1"></a> 39 <span class="phrase"><a name="fiber.fls.cleanup_at_fiber_exit"></a></span><a class="link" href="fls.html#fiber.fls.cleanup_at_fiber_exit">Cleanup 40 at fiber exit</a> 41 </h4> 42<p> 43 When a fiber exits, the objects associated with each <a class="link" href="fls.html#class_fiber_specific_ptr"><code class="computeroutput">fiber_specific_ptr</code></a> instance 44 are destroyed. By default, the object pointed to by a pointer <code class="computeroutput"><span class="identifier">p</span></code> is destroyed by invoking <code class="computeroutput"><span class="keyword">delete</span> <span class="identifier">p</span></code>, 45 but this can be overridden for a specific instance of <a class="link" href="fls.html#class_fiber_specific_ptr"><code class="computeroutput">fiber_specific_ptr</code></a> by 46 providing a cleanup routine <code class="computeroutput"><span class="identifier">func</span></code> 47 to the constructor. In this case, the object is destroyed by invoking <code class="computeroutput"><span class="identifier">func</span><span class="special">(</span><span class="identifier">p</span><span class="special">)</span></code>. The cleanup functions are called in an unspecified 48 order. 49 </p> 50<p> 51 </p> 52<h5> 53<a name="class_fiber_specific_ptr_bridgehead"></a> 54 <span class="phrase"><a name="class_fiber_specific_ptr"></a></span> 55 <a class="link" href="fls.html#class_fiber_specific_ptr">Class 56 <code class="computeroutput">fiber_specific_ptr</code></a> 57</h5> 58<p> 59 </p> 60<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">fss</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 61 62<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> 63<span class="keyword">namespace</span> <span class="identifier">fibers</span> <span class="special">{</span> 64 65<span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">T</span> <span class="special">></span> 66<span class="keyword">class</span> <span class="identifier">fiber_specific_ptr</span> <span class="special">{</span> 67<span class="keyword">public</span><span class="special">:</span> 68 <span class="keyword">typedef</span> <span class="identifier">T</span> <span class="identifier">element_type</span><span class="special">;</span> 69 70 <span class="identifier">fiber_specific_ptr</span><span class="special">();</span> 71 72 <span class="keyword">explicit</span> <span class="identifier">fiber_specific_ptr</span><span class="special">(</span> <span class="keyword">void</span><span class="special">(*</span><span class="identifier">fn</span><span class="special">)(</span><span class="identifier">T</span><span class="special">*)</span> <span class="special">);</span> 73 74 <span class="special">~</span><span class="identifier">fiber_specific_ptr</span><span class="special">();</span> 75 76 <span class="identifier">fiber_specific_ptr</span><span class="special">(</span> <span class="identifier">fiber_specific_ptr</span> <span class="keyword">const</span><span class="special">&)</span> <span class="special">=</span> <span class="keyword">delete</span><span class="special">;</span> 77 <span class="identifier">fiber_specific_ptr</span> <span class="special">&</span> <span class="keyword">operator</span><span class="special">=(</span> <span class="identifier">fiber_specific_ptr</span> <span class="keyword">const</span><span class="special">&)</span> <span class="special">=</span> <span class="keyword">delete</span><span class="special">;</span> 78 79 <span class="identifier">T</span> <span class="special">*</span> <span class="identifier">get</span><span class="special">()</span> <span class="keyword">const</span> <span class="keyword">noexcept</span><span class="special">;</span> 80 81 <span class="identifier">T</span> <span class="special">*</span> <span class="keyword">operator</span><span class="special">->()</span> <span class="keyword">const</span> <span class="keyword">noexcept</span><span class="special">;</span> 82 83 <span class="identifier">T</span> <span class="special">&</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span> <span class="keyword">noexcept</span><span class="special">;</span> 84 85 <span class="identifier">T</span> <span class="special">*</span> <span class="identifier">release</span><span class="special">();</span> 86 87 <span class="keyword">void</span> <span class="identifier">reset</span><span class="special">(</span> <span class="identifier">T</span> <span class="special">*);</span> 88<span class="special">};</span> 89 90<span class="special">}}</span> 91</pre> 92<h4> 93<a name="fiber.fls.h2"></a> 94 <span class="phrase"><a name="fiber.fls.constructor"></a></span><a class="link" href="fls.html#fiber.fls.constructor">Constructor</a> 95 </h4> 96<pre class="programlisting"><span class="identifier">fiber_specific_ptr</span><span class="special">();</span> 97<span class="keyword">explicit</span> <span class="identifier">fiber_specific_ptr</span><span class="special">(</span> <span class="keyword">void</span><span class="special">(*</span><span class="identifier">fn</span><span class="special">)(</span><span class="identifier">T</span><span class="special">*)</span> <span class="special">);</span> 98</pre> 99<div class="variablelist"> 100<p class="title"><b></b></p> 101<dl class="variablelist"> 102<dt><span class="term">Requires:</span></dt> 103<dd><p> 104 <code class="computeroutput"><span class="keyword">delete</span> <span class="keyword">this</span><span class="special">-></span><span class="identifier">get</span><span class="special">()</span></code> is well-formed; <code class="computeroutput"><span class="identifier">fn</span><span class="special">(</span><span class="keyword">this</span><span class="special">-></span><span class="identifier">get</span><span class="special">())</span></code> does not throw 105 </p></dd> 106<dt><span class="term">Effects:</span></dt> 107<dd><p> 108 Construct a <a class="link" href="fls.html#class_fiber_specific_ptr"><code class="computeroutput">fiber_specific_ptr</code></a> object for storing 109 a pointer to an object of type <code class="computeroutput"><span class="identifier">T</span></code> 110 specific to each fiber. When <code class="computeroutput"><span class="identifier">reset</span><span class="special">()</span></code> is called, or the fiber exits, <a class="link" href="fls.html#class_fiber_specific_ptr"><code class="computeroutput">fiber_specific_ptr</code></a> calls 111 <code class="computeroutput"><span class="identifier">fn</span><span class="special">(</span><span class="keyword">this</span><span class="special">-></span><span class="identifier">get</span><span class="special">())</span></code>. 112 If the no-arguments constructor is used, the default <code class="computeroutput"><span class="keyword">delete</span></code>-based 113 cleanup function will be used to destroy the fiber-local objects. 114 </p></dd> 115<dt><span class="term">Throws:</span></dt> 116<dd><p> 117 <code class="computeroutput"><span class="identifier">fiber_error</span></code> if an error 118 occurs. 119 </p></dd> 120</dl> 121</div> 122<h4> 123<a name="fiber.fls.h3"></a> 124 <span class="phrase"><a name="fiber.fls.destructor"></a></span><a class="link" href="fls.html#fiber.fls.destructor">Destructor</a> 125 </h4> 126<pre class="programlisting"><span class="special">~</span><span class="identifier">fiber_specific_ptr</span><span class="special">();</span> 127</pre> 128<div class="variablelist"> 129<p class="title"><b></b></p> 130<dl class="variablelist"> 131<dt><span class="term">Requires:</span></dt> 132<dd><p> 133 All the fiber specific instances associated to this <a class="link" href="fls.html#class_fiber_specific_ptr"><code class="computeroutput">fiber_specific_ptr</code></a> 134(except 135 maybe the one associated to this fiber) must be nullptr. 136 </p></dd> 137<dt><span class="term">Effects:</span></dt> 138<dd><p> 139 Calls <code class="computeroutput"><span class="keyword">this</span><span class="special">-></span><span class="identifier">reset</span><span class="special">()</span></code> 140 to clean up the associated value for the current fiber, and destroys 141 <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>. 142 </p></dd> 143<dt><span class="term">Remarks:</span></dt> 144<dd><p> 145 The requirement is an implementation restriction. If the destructor promised 146 to delete instances for all fibers, the implementation would be forced 147 to maintain a list of all the fibers having an associated specific ptr, 148 which is against the goal of fiber specific data. In general, a <a class="link" href="fls.html#class_fiber_specific_ptr"><code class="computeroutput">fiber_specific_ptr</code></a> should 149 outlive the fibers that use it. 150 </p></dd> 151</dl> 152</div> 153<div class="note"><table border="0" summary="Note"> 154<tr> 155<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 156<th align="left">Note</th> 157</tr> 158<tr><td align="left" valign="top"><p> 159 Care needs to be taken to ensure that any fibers still running after an instance 160 of <a class="link" href="fls.html#class_fiber_specific_ptr"><code class="computeroutput">fiber_specific_ptr</code></a> has been destroyed do not call 161 any member functions on that instance. 162 </p></td></tr> 163</table></div> 164<p> 165 </p> 166<h5> 167<a name="fiber_specific_ptr_get_bridgehead"></a> 168 <span class="phrase"><a name="fiber_specific_ptr_get"></a></span> 169 <a class="link" href="fls.html#fiber_specific_ptr_get">Member 170 function <code class="computeroutput">get</code>()</a> 171</h5> 172<p> 173 </p> 174<pre class="programlisting"><span class="identifier">T</span> <span class="special">*</span> <span class="identifier">get</span><span class="special">()</span> <span class="keyword">const</span> <span class="keyword">noexcept</span><span class="special">;</span> 175</pre> 176<div class="variablelist"> 177<p class="title"><b></b></p> 178<dl class="variablelist"> 179<dt><span class="term">Returns:</span></dt> 180<dd><p> 181 The pointer associated with the current fiber. 182 </p></dd> 183<dt><span class="term">Throws:</span></dt> 184<dd><p> 185 Nothing. 186 </p></dd> 187</dl> 188</div> 189<div class="note"><table border="0" summary="Note"> 190<tr> 191<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 192<th align="left">Note</th> 193</tr> 194<tr><td align="left" valign="top"><p> 195 The initial value associated with an instance of <a class="link" href="fls.html#class_fiber_specific_ptr"><code class="computeroutput">fiber_specific_ptr</code></a> is 196 <code class="computeroutput"><span class="keyword">nullptr</span></code> for each fiber. 197 </p></td></tr> 198</table></div> 199<p> 200 </p> 201<h5> 202<a name="fiber_specific_ptr_operator_arrow_bridgehead"></a> 203 <span class="phrase"><a name="fiber_specific_ptr_operator_arrow"></a></span> 204 <a class="link" href="fls.html#fiber_specific_ptr_operator_arrow">Member 205 function <code class="computeroutput">operator-></code>()</a> 206</h5> 207<p> 208 </p> 209<pre class="programlisting"><span class="identifier">T</span> <span class="special">*</span> <span class="keyword">operator</span><span class="special">->()</span> <span class="keyword">const</span> <span class="keyword">noexcept</span><span class="special">;</span> 210</pre> 211<div class="variablelist"> 212<p class="title"><b></b></p> 213<dl class="variablelist"> 214<dt><span class="term">Requires:</span></dt> 215<dd><p> 216 <code class="computeroutput"><span class="keyword">this</span><span class="special">-></span><span class="identifier">get</span><span class="special">()</span></code> 217 is not <code class="computeroutput"><span class="keyword">nullptr</span></code>. 218 </p></dd> 219<dt><span class="term">Returns:</span></dt> 220<dd><p> 221 <code class="computeroutput"><span class="keyword">this</span><span class="special">-></span><span class="identifier">get</span><span class="special">()</span></code> 222 </p></dd> 223<dt><span class="term">Throws:</span></dt> 224<dd><p> 225 Nothing. 226 </p></dd> 227</dl> 228</div> 229<p> 230 </p> 231<h5> 232<a name="fiber_specific_ptr_operator_star_bridgehead"></a> 233 <span class="phrase"><a name="fiber_specific_ptr_operator_star"></a></span> 234 <a class="link" href="fls.html#fiber_specific_ptr_operator_star">Member 235 function <code class="computeroutput">operator*</code>()</a> 236</h5> 237<p> 238 </p> 239<pre class="programlisting"><span class="identifier">T</span> <span class="special">&</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span> <span class="keyword">noexcept</span><span class="special">;</span> 240</pre> 241<div class="variablelist"> 242<p class="title"><b></b></p> 243<dl class="variablelist"> 244<dt><span class="term">Requires:</span></dt> 245<dd><p> 246 <code class="computeroutput"><span class="keyword">this</span><span class="special">-></span><span class="identifier">get</span><span class="special">()</span></code> 247 is not <code class="computeroutput"><span class="keyword">nullptr</span></code>. 248 </p></dd> 249<dt><span class="term">Returns:</span></dt> 250<dd><p> 251 <code class="computeroutput"><span class="special">*(</span><span class="keyword">this</span><span class="special">-></span><span class="identifier">get</span><span class="special">())</span></code> 252 </p></dd> 253<dt><span class="term">Throws:</span></dt> 254<dd><p> 255 Nothing. 256 </p></dd> 257</dl> 258</div> 259<p> 260 </p> 261<h5> 262<a name="fiber_specific_ptr_release_bridgehead"></a> 263 <span class="phrase"><a name="fiber_specific_ptr_release"></a></span> 264 <a class="link" href="fls.html#fiber_specific_ptr_release">Member 265 function <code class="computeroutput">release</code>()</a> 266</h5> 267<p> 268 </p> 269<pre class="programlisting"><span class="identifier">T</span> <span class="special">*</span> <span class="identifier">release</span><span class="special">();</span> 270</pre> 271<div class="variablelist"> 272<p class="title"><b></b></p> 273<dl class="variablelist"> 274<dt><span class="term">Effects:</span></dt> 275<dd><p> 276 Return <code class="computeroutput"><span class="keyword">this</span><span class="special">-></span><span class="identifier">get</span><span class="special">()</span></code> 277 and store <code class="computeroutput"><span class="keyword">nullptr</span></code> as the 278 pointer associated with the current fiber without invoking the cleanup 279 function. 280 </p></dd> 281<dt><span class="term">Postcondition:</span></dt> 282<dd><p> 283 <code class="computeroutput"><span class="keyword">this</span><span class="special">-></span><span class="identifier">get</span><span class="special">()==</span><span class="keyword">nullptr</span></code> 284 </p></dd> 285<dt><span class="term">Throws:</span></dt> 286<dd><p> 287 Nothing. 288 </p></dd> 289</dl> 290</div> 291<p> 292 </p> 293<h5> 294<a name="fiber_specific_ptr_reset_bridgehead"></a> 295 <span class="phrase"><a name="fiber_specific_ptr_reset"></a></span> 296 <a class="link" href="fls.html#fiber_specific_ptr_reset">Member 297 function <code class="computeroutput">reset</code>()</a> 298</h5> 299<p> 300 </p> 301<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">reset</span><span class="special">(</span> <span class="identifier">T</span> <span class="special">*</span> <span class="identifier">new_value</span><span class="special">);</span> 302</pre> 303<div class="variablelist"> 304<p class="title"><b></b></p> 305<dl class="variablelist"> 306<dt><span class="term">Effects:</span></dt> 307<dd><p> 308 If <code class="computeroutput"><span class="keyword">this</span><span class="special">-></span><span class="identifier">get</span><span class="special">()!=</span><span class="identifier">new_value</span></code> and <code class="computeroutput"><span class="keyword">this</span><span class="special">-></span><span class="identifier">get</span><span class="special">()</span></code> is not <code class="computeroutput"><span class="keyword">nullptr</span></code>, 309 invoke <code class="computeroutput"><span class="keyword">delete</span> <span class="keyword">this</span><span class="special">-></span><span class="identifier">get</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">fn</span><span class="special">(</span><span class="keyword">this</span><span class="special">-></span><span class="identifier">get</span><span class="special">())</span></code> as appropriate. Store <code class="computeroutput"><span class="identifier">new_value</span></code> as the pointer associated 310 with the current fiber. 311 </p></dd> 312<dt><span class="term">Postcondition:</span></dt> 313<dd><p> 314 <code class="computeroutput"><span class="keyword">this</span><span class="special">-></span><span class="identifier">get</span><span class="special">()==</span><span class="identifier">new_value</span></code> 315 </p></dd> 316<dt><span class="term">Throws:</span></dt> 317<dd><p> 318 Exception raised during cleanup of previous value. 319 </p></dd> 320</dl> 321</div> 322</div> 323<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 324<td align="left"></td> 325<td align="right"><div class="copyright-footer">Copyright © 2013 Oliver Kowalke<p> 326 Distributed under the Boost Software License, Version 1.0. (See accompanying 327 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>) 328 </p> 329</div></td> 330</tr></table> 331<hr> 332<div class="spirit-nav"> 333<a accesskey="p" href="synchronization/futures/packaged_task.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="migration.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 334</div> 335</body> 336</html> 337
