ceph/src/boost/libs/fiber/doc/html/fiber/fls.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   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.75.2">
   7 <link rel="home" href="../index.html" title="Chapter&#160;1.&#160;Fiber">
   8 <link rel="up" href="../index.html" title="Chapter&#160;1.&#160;Fiber">
   9 <link rel="prev" href="synchronization/futures/packaged_task.html" title="Template packaged_task&lt;&gt;">
  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><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><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><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">&lt;</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">&gt;</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">&lt;</span> <span class="keyword">typename</span> <span class="identifier">T</span> <span class="special">&gt;</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">&amp;)</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">&amp;</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">&amp;)</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">-&gt;()</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">&amp;</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><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>
 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">-&gt;</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">-&gt;</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">-&gt;</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><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>
 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">-&gt;</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><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>
 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><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-&gt;</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">-&gt;()</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>
 214 <dt><span class="term">Requires:</span></dt>
 215 <dd><p>
 216             <code class="computeroutput"><span class="keyword">this</span><span class="special">-&gt;</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">-&gt;</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><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">&amp;</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>
 244 <dt><span class="term">Requires:</span></dt>
 245 <dd><p>
 246             <code class="computeroutput"><span class="keyword">this</span><span class="special">-&gt;</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">-&gt;</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><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>
 274 <dt><span class="term">Effects:</span></dt>
 275 <dd><p>
 276             Return <code class="computeroutput"><span class="keyword">this</span><span class="special">-&gt;</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">-&gt;</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><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>
 306 <dt><span class="term">Effects:</span></dt>
 307 <dd><p>
 308             If <code class="computeroutput"><span class="keyword">this</span><span class="special">-&gt;</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">-&gt;</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">-&gt;</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">-&gt;</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">-&gt;</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 &#169; 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>