[ceph.git] / ceph / src / boost / libs / fiber / doc / html / fiber / fiber_mgmt.html

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Fiber management</title>
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="../index.html" title="Chapter&#160;1.&#160;Fiber">
<link rel="up" href="../index.html" title="Chapter&#160;1.&#160;Fiber">
<link rel="prev" href="overview.html" title="Overview">
<link rel="next" href="fiber_mgmt/fiber.html" title="Class fiber">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
<td align="center"><a href="../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="overview.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="fiber_mgmt/fiber.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="fiber.fiber_mgmt"></a><a class="link" href="fiber_mgmt.html" title="Fiber management">Fiber management</a>
</h2></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="fiber_mgmt/fiber.html">Class
      <code class="computeroutput"><span class="identifier">fiber</span></code></a></span></dt>
<dt><span class="section"><a href="fiber_mgmt/id.html">Class fiber::id</a></span></dt>
<dt><span class="section"><a href="fiber_mgmt/this_fiber.html">Namespace this_fiber</a></span></dt>
</dl></div>
<h4>
<a name="fiber.fiber_mgmt.h0"></a>
      <span><a name="fiber.fiber_mgmt.synopsis"></a></span><a class="link" href="fiber_mgmt.html#fiber.fiber_mgmt.synopsis">Synopsis</a>
    </h4>
<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">all</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>

<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
<span class="keyword">namespace</span> <span class="identifier">fibers</span> <span class="special">{</span>

<span class="keyword">class</span> <span class="identifier">fiber</span><span class="special">;</span>
<span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">&lt;(</span> <span class="identifier">fiber</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">l</span><span class="special">,</span> <span class="identifier">fiber</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">r</span><span class="special">)</span> <span class="keyword">noexcept</span><span class="special">;</span>
<span class="keyword">void</span> <span class="identifier">swap</span><span class="special">(</span> <span class="identifier">fiber</span> <span class="special">&amp;</span> <span class="identifier">l</span><span class="special">,</span> <span class="identifier">fiber</span> <span class="special">&amp;</span> <span class="identifier">r</span><span class="special">)</span> <span class="keyword">noexcept</span><span class="special">;</span>

<span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">typename</span> <span class="identifier">SchedAlgo</span><span class="special">,</span> <span class="keyword">typename</span> <span class="special">...</span> <span class="identifier">Args</span> <span class="special">&gt;</span>
<span class="keyword">void</span> <span class="identifier">use_scheduling_algorithm</span><span class="special">(</span> <span class="identifier">Args</span> <span class="special">&amp;&amp;</span> <span class="special">...</span> <span class="identifier">args</span><span class="special">);</span>
<span class="keyword">bool</span> <span class="identifier">has_ready_fibers</span><span class="special">();</span>

<span class="keyword">namespace</span> <span class="identifier">algo</span> <span class="special">{</span>

<span class="keyword">struct</span> <span class="identifier">algorithm</span><span class="special">;</span>
<span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">typename</span> <span class="identifier">PROPS</span> <span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">algorithm_with_properties</span><span class="special">;</span>
<span class="keyword">class</span> <span class="identifier">round_robin</span><span class="special">;</span>
<span class="keyword">class</span> <span class="identifier">shared_round_robin</span><span class="special">;</span>

<span class="special">}</span>

<span class="keyword">namespace</span> <span class="identifier">this_fiber</span> <span class="special">{</span>

<span class="identifier">fibers</span><span class="special">::</span><span class="identifier">id</span> <span class="identifier">get_id</span><span class="special">()</span> <span class="keyword">noexcept</span><span class="special">;</span>
<span class="keyword">void</span> <span class="identifier">yield</span><span class="special">();</span>
<span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">typename</span> <span class="identifier">Clock</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Duration</span> <span class="special">&gt;</span>
<span class="keyword">void</span> <span class="identifier">sleep_until</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">chrono</span><span class="special">::</span><span class="identifier">time_point</span><span class="special">&lt;</span> <span class="identifier">Clock</span><span class="special">,</span> <span class="identifier">Duration</span> <span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">abs_time</span><span class="special">)</span>
<span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">typename</span> <span class="identifier">Rep</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Period</span> <span class="special">&gt;</span>
<span class="keyword">void</span> <span class="identifier">sleep_for</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">chrono</span><span class="special">::</span><span class="identifier">duration</span><span class="special">&lt;</span> <span class="identifier">Rep</span><span class="special">,</span> <span class="identifier">Period</span> <span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">rel_time</span><span class="special">);</span>
<span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">typename</span> <span class="identifier">PROPS</span> <span class="special">&gt;</span>
<span class="identifier">PROPS</span> <span class="special">&amp;</span> <span class="identifier">properties</span><span class="special">();</span>

<span class="special">}}</span>
</pre>
<h4>
<a name="fiber.fiber_mgmt.h1"></a>
      <span><a name="fiber.fiber_mgmt.tutorial"></a></span><a class="link" href="fiber_mgmt.html#fiber.fiber_mgmt.tutorial">Tutorial</a>
    </h4>
<p>
      Each <a class="link" href="fiber_mgmt/fiber.html#class_fiber"><code class="computeroutput">fiber</code></a> represents a micro-thread which will be launched and managed
      cooperatively by a scheduler. Objects of type <a class="link" href="fiber_mgmt/fiber.html#class_fiber"><code class="computeroutput">fiber</code></a> are move-only.
    </p>
<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">fiber</span> <span class="identifier">f1</span><span class="special">;</span> <span class="comment">// not-a-fiber</span>

<span class="keyword">void</span> <span class="identifier">f</span><span class="special">()</span> <span class="special">{</span>
    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">fiber</span> <span class="identifier">f2</span><span class="special">(</span> <span class="identifier">some_fn</span><span class="special">);</span>

    <span class="identifier">f1</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span> <span class="identifier">f2</span><span class="special">);</span> <span class="comment">// f2 moved to f1</span>
<span class="special">}</span>
</pre>
<h4>
<a name="fiber.fiber_mgmt.h2"></a>
      <span><a name="fiber.fiber_mgmt.launching"></a></span><a class="link" href="fiber_mgmt.html#fiber.fiber_mgmt.launching">Launching</a>
    </h4>
<p>
      A new fiber is launched by passing an object of a callable type that can be
      invoked with no parameters. If the object must not be copied or moved, then
      <span class="emphasis"><em>std::ref</em></span> can be used to pass in a reference to the function
      object. In this case, the user must ensure that the referenced object outlives
      the newly-created fiber.
    </p>
<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">callable</span> <span class="special">{</span>
    <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()();</span>
<span class="special">};</span>

<span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">fiber</span> <span class="identifier">copies_are_safe</span><span class="special">()</span> <span class="special">{</span>
    <span class="identifier">callable</span> <span class="identifier">x</span><span class="special">;</span>
    <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">fiber</span><span class="special">(</span> <span class="identifier">x</span><span class="special">);</span>
<span class="special">}</span> <span class="comment">// x is destroyed, but the newly-created fiber has a copy, so this is OK</span>

<span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">fiber</span> <span class="identifier">oops</span><span class="special">()</span> <span class="special">{</span>
    <span class="identifier">callable</span> <span class="identifier">x</span><span class="special">;</span>
    <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">fiber</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ref</span><span class="special">(</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">);</span>
<span class="special">}</span> <span class="comment">// x is destroyed, but the newly-created fiber still has a reference</span>
  <span class="comment">// this leads to undefined behaviour</span>
</pre>
<p>
      The spawned <a class="link" href="fiber_mgmt/fiber.html#class_fiber"><code class="computeroutput">fiber</code></a> does not immediately start running. It is enqueued
      in the list of ready-to-run fibers, and will run when the scheduler gets around
      to it.
    </p>
<a name="exceptions"></a><h4>
<a name="fiber.fiber_mgmt.h3"></a>
      <span><a name="fiber.fiber_mgmt.exceptions"></a></span><a class="link" href="fiber_mgmt.html#fiber.fiber_mgmt.exceptions">Exceptions</a>
    </h4>
<p>
      An exception escaping from the function or callable object passed to the <a class="link" href="fiber_mgmt/fiber.html#class_fiber"><code class="computeroutput">fiber</code></a>
constructor
      calls <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">terminate</span><span class="special">()</span></code>.
      If you need to know which exception was thrown, use <a class="link" href="synchronization/futures/future.html#class_future"><code class="computeroutput">future&lt;&gt;</code></a> or
      <a class="link" href="synchronization/futures/packaged_task.html#class_packaged_task"><code class="computeroutput">packaged_task&lt;&gt;</code></a>.
    </p>
<h4>
<a name="fiber.fiber_mgmt.h4"></a>
      <span><a name="fiber.fiber_mgmt.detaching"></a></span><a class="link" href="fiber_mgmt.html#fiber.fiber_mgmt.detaching">Detaching</a>
    </h4>
<p>
      A <a class="link" href="fiber_mgmt/fiber.html#class_fiber"><code class="computeroutput">fiber</code></a> can be detached by explicitly invoking the <a class="link" href="fiber_mgmt/fiber.html#fiber_detach"><code class="computeroutput">fiber::detach()</code></a> member
      function. After <a class="link" href="fiber_mgmt/fiber.html#fiber_detach"><code class="computeroutput">fiber::detach()</code></a> is called on a fiber object, that
      object represents <span class="emphasis"><em>not-a-fiber</em></span>. The fiber object may then
      safely be destroyed.
    </p>
<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">fiber</span><span class="special">(</span> <span class="identifier">some_fn</span><span class="special">).</span><span class="identifier">detach</span><span class="special">();</span>
</pre>
<p>
      <span class="bold"><strong>Boost.Fiber</strong></span> provides a number of ways to wait
      for a running fiber to complete. You can coordinate even with a detached fiber
      using a <a class="link" href="synchronization/mutex_types.html#class_mutex"><code class="computeroutput">mutex</code></a>, or <a class="link" href="synchronization/conditions.html#class_condition_variable"><code class="computeroutput">condition_variable</code></a>, or
      any of the other <a class="link" href="synchronization.html#synchronization">synchronization objects</a>
      provided by the library.
    </p>
<p>
      If a detached fiber is still running when the thread&#8217;s main fiber terminates,
      the thread will not shut down.
    </p>
<h4>
<a name="fiber.fiber_mgmt.h5"></a>
      <span><a name="fiber.fiber_mgmt.joining"></a></span><a class="link" href="fiber_mgmt.html#fiber.fiber_mgmt.joining">Joining</a>
    </h4>
<p>
      In order to wait for a fiber to finish, the <a class="link" href="fiber_mgmt/fiber.html#fiber_join"><code class="computeroutput">fiber::join()</code></a> member function
      of the <a class="link" href="fiber_mgmt/fiber.html#class_fiber"><code class="computeroutput">fiber</code></a> object can be used. <a class="link" href="fiber_mgmt/fiber.html#fiber_join"><code class="computeroutput">fiber::join()</code></a> will block
      until the <a class="link" href="fiber_mgmt/fiber.html#class_fiber"><code class="computeroutput">fiber</code></a> object has completed.
    </p>
<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">some_fn</span><span class="special">()</span> <span class="special">{</span>
    <span class="special">...</span>
<span class="special">}</span>

<span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">fiber</span> <span class="identifier">f</span><span class="special">(</span> <span class="identifier">some_fn</span><span class="special">);</span>
<span class="special">...</span>
<span class="identifier">f</span><span class="special">.</span><span class="identifier">join</span><span class="special">();</span>
</pre>
<p>
      If the fiber has already completed, then <a class="link" href="fiber_mgmt/fiber.html#fiber_join"><code class="computeroutput">fiber::join()</code></a> returns immediately
      and the joined <a class="link" href="fiber_mgmt/fiber.html#class_fiber"><code class="computeroutput">fiber</code></a> object becomes <span class="emphasis"><em>not-a-fiber</em></span>.
    </p>
<h4>
<a name="fiber.fiber_mgmt.h6"></a>
      <span><a name="fiber.fiber_mgmt.destruction"></a></span><a class="link" href="fiber_mgmt.html#fiber.fiber_mgmt.destruction">Destruction</a>
    </h4>
<p>
      When a <a class="link" href="fiber_mgmt/fiber.html#class_fiber"><code class="computeroutput">fiber</code></a> object representing a valid execution context (the fiber
      is <a class="link" href="fiber_mgmt/fiber.html#fiber_joinable"><code class="computeroutput">fiber::joinable()</code></a>) is destroyed, the program terminates. If
      you intend the fiber to outlive the <a class="link" href="fiber_mgmt/fiber.html#class_fiber"><code class="computeroutput">fiber</code></a> object that launched it,
      use the <a class="link" href="fiber_mgmt/fiber.html#fiber_detach"><code class="computeroutput">fiber::detach()</code></a> method.
    </p>
<pre class="programlisting"><span class="special">{</span>
    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">fiber</span> <span class="identifier">f</span><span class="special">(</span> <span class="identifier">some_fn</span><span class="special">);</span>
<span class="special">}</span> <span class="comment">// std::terminate() will be called</span>

<span class="special">{</span>
    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">fiber</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">some_fn</span><span class="special">);</span>
    <span class="identifier">f</span><span class="special">.</span><span class="identifier">detach</span><span class="special">();</span>
<span class="special">}</span> <span class="comment">// okay, program continues</span>
</pre>
<a name="class_fiber_id"></a><h4>
<a name="fiber.fiber_mgmt.h7"></a>
      <span><a name="fiber.fiber_mgmt.fiber_ids"></a></span><a class="link" href="fiber_mgmt.html#fiber.fiber_mgmt.fiber_ids">Fiber
      IDs</a>
    </h4>
<p>
      Objects of class <a class="link" href="fiber_mgmt.html#class_fiber_id"><code class="computeroutput"><span class="identifier">fiber</span><span class="special">::</span><span class="identifier">id</span></code></a> can be
      used to identify fibers. Each running <a class="link" href="fiber_mgmt/fiber.html#class_fiber"><code class="computeroutput">fiber</code></a> has a unique <a class="link" href="fiber_mgmt.html#class_fiber_id"><code class="computeroutput"><span class="identifier">fiber</span><span class="special">::</span><span class="identifier">id</span></code></a> obtainable
      from the corresponding <a class="link" href="fiber_mgmt/fiber.html#class_fiber"><code class="computeroutput">fiber</code></a>
by calling the <a class="link" href="fiber_mgmt/fiber.html#fiber_get_id"><code class="computeroutput">fiber::get_id()</code></a> member
      function. Objects of class <a class="link" href="fiber_mgmt.html#class_fiber_id"><code class="computeroutput"><span class="identifier">fiber</span><span class="special">::</span><span class="identifier">id</span></code></a> can be
      copied, and used as keys in associative containers: the full range of comparison
      operators is provided. They can also be written to an output stream using the
      stream insertion operator, though the output format is unspecified.
    </p>
<p>
      Each instance of <a class="link" href="fiber_mgmt.html#class_fiber_id"><code class="computeroutput"><span class="identifier">fiber</span><span class="special">::</span><span class="identifier">id</span></code></a> either
      refers to some fiber, or <span class="emphasis"><em>not-a-fiber</em></span>. Instances that refer
      to <span class="emphasis"><em>not-a-fiber</em></span> compare equal to each other, but not equal
      to any instances that refer to an actual fiber. The comparison operators on
      <a class="link" href="fiber_mgmt.html#class_fiber_id"><code class="computeroutput"><span class="identifier">fiber</span><span class="special">::</span><span class="identifier">id</span></code></a> yield a total order for every non-equal
      <a class="link" href="fiber_mgmt.html#class_fiber_id"><code class="computeroutput"><span class="identifier">fiber</span><span class="special">::</span><span class="identifier">id</span></code></a>.
    </p>
<a name="class_launch"></a><h4>
<a name="fiber.fiber_mgmt.h8"></a>
      <span><a name="fiber.fiber_mgmt.enumeration__code__phrase_role__identifier__launch__phrase___code_"></a></span><a class="link" href="fiber_mgmt.html#fiber.fiber_mgmt.enumeration__code__phrase_role__identifier__launch__phrase___code_">Enumeration
      <code class="computeroutput"><span class="identifier">launch</span></code></a>
    </h4>
<p>
      <code class="computeroutput"><span class="identifier">launch</span></code> specifies whether control
      passes immediately into a newly-launched fiber.
    </p>
<pre class="programlisting"><span class="keyword">enum</span> <span class="keyword">class</span> <span class="identifier">launch</span> <span class="special">{</span>
    <span class="identifier">dispatch</span><span class="special">,</span>
    <span class="identifier">post</span>
<span class="special">};</span>
</pre>
<h4>
<a name="fiber.fiber_mgmt.h9"></a>
      <span><a name="fiber.fiber_mgmt._code__phrase_role__identifier__dispatch__phrase___code_"></a></span><a class="link" href="fiber_mgmt.html#fiber.fiber_mgmt._code__phrase_role__identifier__dispatch__phrase___code_"><code class="computeroutput"><span class="identifier">dispatch</span></code></a>
    </h4>
<div class="variablelist">
<p class="title"><b></b></p>
<dl>
<dt><span class="term">Effects:</span></dt>
<dd><p>
            A fiber launched with <code class="computeroutput"><span class="identifier">launch</span>
            <span class="special">==</span> <span class="identifier">dispatch</span></code>
            is entered immediately. In other words, launching a fiber with <code class="computeroutput"><span class="identifier">dispatch</span></code> suspends the caller (the previously-running
            fiber) until the fiber scheduler has a chance to resume it later.
          </p></dd>
</dl>
</div>
<h4>
<a name="fiber.fiber_mgmt.h10"></a>
      <span><a name="fiber.fiber_mgmt._code__phrase_role__identifier__post__phrase___code_"></a></span><a class="link" href="fiber_mgmt.html#fiber.fiber_mgmt._code__phrase_role__identifier__post__phrase___code_"><code class="computeroutput"><span class="identifier">post</span></code></a>
    </h4>
<div class="variablelist">
<p class="title"><b></b></p>
<dl>
<dt><span class="term">Effects:</span></dt>
<dd><p>
            A fiber launched with <code class="computeroutput"><span class="identifier">launch</span>
            <span class="special">==</span> <span class="identifier">post</span></code>
            is passed to the fiber scheduler as ready, but it is not yet entered.
            The caller (the previously-running fiber) continues executing. The newly-launched
            fiber will be entered when the fiber scheduler has a chance to resume
            it later.
          </p></dd>
<dt><span class="term">Note:</span></dt>
<dd><p>
            If <code class="computeroutput"><span class="identifier">launch</span></code> is not explicitly
            specified, <code class="computeroutput"><span class="identifier">post</span></code> is the
            default.
          </p></dd>
</dl>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2013 Oliver Kowalke<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        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>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="overview.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="fiber_mgmt/fiber.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>