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

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Overview</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="../index.html" title="Chapter&#160;1.&#160;Fiber">
  10 <link rel="next" href="fiber_mgmt.html" title="Fiber management">
  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="../index.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.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.overview"></a><a class="link" href="overview.html" title="Overview">Overview</a>
  28 </h2></div></div></div>
  29 <p>
  30       <span class="bold"><strong>Boost.Fiber</strong></span> provides a framework for micro-/userland-threads
  31       (fibers) scheduled cooperatively. The API contains classes and functions to
  32       manage and synchronize fibers similiarly to <a href="http://en.cppreference.com/w/cpp/thread" target="_top">standard
  33       thread support library</a>.
  34     </p>
  35 <p>
  36       Each fiber has its own stack.
  37     </p>
  38 <p>
  39       A fiber can save the current execution state, including all registers and CPU
  40       flags, the instruction pointer, and the stack pointer and later restore this
  41       state. The idea is to have multiple execution paths running on a single thread
  42       using cooperative scheduling (versus threads, which are preemptively scheduled).
  43       The running fiber decides explicitly when it should yield to allow another
  44       fiber to run (context switching). <span class="bold"><strong>Boost.Fiber</strong></span>
  45       internally uses <a href="http://www.boost.org/doc/libs/release/libs/context/doc/html/context/econtext.html" target="_top"><span class="emphasis"><em>execution_context</em></span></a>
  46       from <a href="http://www.boost.org/doc/libs/release/libs/context/index.html" target="_top">Boost.Context</a>;
  47       the classes in this library manage, schedule and, when needed, synchronize
  48       those execution contexts. A context switch between threads usually costs thousands
  49       of CPU cycles on x86, compared to a fiber switch with less than a hundred cycles.
  50       A fiber runs on a single thread at any point in time.
  51     </p>
  52 <p>
  53       In order to use the classes and functions described here, you can either include
  54       the specific headers specified by the descriptions of each class or function,
  55       or include the master library header:
  56     </p>
  57 <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>
  58 </pre>
  59 <p>
  60       which includes all the other headers in turn.
  61     </p>
  62 <p>
  63       The namespaces used are:
  64     </p>
  65 <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span>
  66 <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">this_fiber</span>
  67 </pre>
  68 <h4>
  69 <a name="fiber.overview.h0"></a>
  70       <span><a name="fiber.overview.fibers_and_threads"></a></span><a class="link" href="overview.html#fiber.overview.fibers_and_threads">Fibers
  71       and Threads</a>
  72     </h4>
  73 <p>
  74       Control is cooperatively passed between fibers launched on a given thread.
  75       At a given moment, on a given thread, at most one fiber is running.
  76     </p>
  77 <p>
  78       Spawning additional fibers on a given thread does not distribute your program
  79       across more hardware cores, though it can make more effective use of the core
  80       on which it's running.
  81     </p>
  82 <p>
  83       On the other hand, a fiber may safely access any resource exclusively owned
  84       by its parent thread without explicitly needing to defend that resource against
  85       concurrent access by other fibers on the same thread. You are already guaranteed
  86       that no other fiber on that thread is concurrently touching that resource.
  87       This can be particularly important when introducing concurrency in legacy code.
  88       You can safely spawn fibers running old code, using asynchronous I/O to interleave
  89       execution.
  90     </p>
  91 <p>
  92       In effect, fibers provide a natural way to organize concurrent code based on
  93       asynchronous I/O. Instead of chaining together completion handlers, code running
  94       on a fiber can make what looks like a normal blocking function call. That call
  95       can cheaply suspend the calling fiber, allowing other fibers on the same thread
  96       to run. When the operation has completed, the suspended fiber resumes, without
  97       having to explicitly save or restore its state. Its local stack variables persist
  98       across the call.
  99     </p>
 100 <p>
 101       A fiber can be migrated from one thread to another, though the library does
 102       not do this by default. It is possible for you to supply a custom scheduler
 103       that migrates fibers between threads. You may specify custom fiber properties
 104       to help your scheduler decide which fibers are permitted to migrate. Please
 105       see <a class="link" href="migration.html#migration">Migrating fibers between threads</a> and
 106       <a class="link" href="custom.html#custom">Customization</a> for more details.
 107     </p>
 108 <p>
 109       A fiber launched on a particular thread continues running on that thread unless
 110       migrated. It might be unblocked (see <a class="link" href="overview.html#blocking">Blocking</a>
 111       below) by some other thread, but that only transitions the fiber from <span class="quote">&#8220;<span class="quote">blocked</span>&#8221;</span>
 112       to <span class="quote">&#8220;<span class="quote">ready</span>&#8221;</span> on its current thread &#8212; it does not cause the fiber to
 113       resume on the thread that unblocked it.
 114     </p>
 115 <a name="thread_local_storage"></a><h4>
 116 <a name="fiber.overview.h1"></a>
 117       <span><a name="fiber.overview.thread_local_storage"></a></span><a class="link" href="overview.html#fiber.overview.thread_local_storage">thread-local
 118       storage</a>
 119     </h4>
 120 <p>
 121       Unless migrated, a fiber may access thread-local storage; however that storage
 122       will be shared among all fibers running on the same thread. For fiber-local
 123       storage, please see <a class="link" href="fls.html#class_fiber_specific_ptr"><code class="computeroutput">fiber_specific_ptr</code></a>.
 124     </p>
 125 <a name="cross_thread_sync"></a><h4>
 126 <a name="fiber.overview.h2"></a>
 127       <span><a name="fiber.overview.boost_fibers_no_atomics"></a></span><a class="link" href="overview.html#fiber.overview.boost_fibers_no_atomics">BOOST_FIBERS_NO_ATOMICS</a>
 128     </h4>
 129 <p>
 130       The fiber synchronization objects provided by this library will, by default,
 131       safely synchronize fibers running on different threads. However, this level
 132       of synchronization can be removed (for performance) by building the library
 133       with <span class="bold"><strong><code class="computeroutput"><span class="identifier">BOOST_FIBERS_NO_ATOMICS</span></code></strong></span>
 134       defined. When the library is built with that macro, you must ensure that all
 135       the fibers referencing a particular synchronization object are running in the
 136       same thread. Please see <a class="link" href="synchronization.html#synchronization">Synchronization</a>.
 137     </p>
 138 <a name="blocking"></a><h4>
 139 <a name="fiber.overview.h3"></a>
 140       <span><a name="fiber.overview.blocking"></a></span><a class="link" href="overview.html#fiber.overview.blocking">Blocking</a>
 141     </h4>
 142 <p>
 143       Normally, when this documentation states that a particular fiber <span class="emphasis"><em>blocks</em></span>
 144       (or equivalently, <span class="emphasis"><em>suspends),</em></span> it means that it yields control,
 145       allowing other fibers on the same thread to run. The synchronization mechanisms
 146       provided by <span class="bold"><strong>Boost.Fiber</strong></span> have this behavior.
 147     </p>
 148 <p>
 149       A fiber may, of course, use normal thread synchronization mechanisms; however
 150       a fiber that invokes any of these mechanisms will block its entire thread,
 151       preventing any other fiber from running on that thread in the meantime. For
 152       instance, when a fiber wants to wait for a value from another fiber in the
 153       same thread, using <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">future</span></code> would be unfortunate: <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">future</span><span class="special">::</span><span class="identifier">get</span><span class="special">()</span></code>
 154       would block the whole thread, preventing the other fiber from delivering its
 155       value. Use <a class="link" href="synchronization/futures/future.html#class_future"><code class="computeroutput">future&lt;&gt;</code></a> instead.
 156     </p>
 157 <p>
 158       Similarly, a fiber that invokes a normal blocking I/O operation will block
 159       its entire thread. Fiber authors are encouraged to consistently use asynchronous
 160       I/O. <a href="http://www.boost.org/doc/libs/release/libs/asio/index.html" target="_top">Boost.Asio</a>
 161       and other asynchronous I/O operations can straightforwardly be adapted for
 162       <span class="bold"><strong>Boost.Fiber</strong></span>: see <a class="link" href="callbacks.html#callbacks">Integrating
 163       Fibers with Asynchronous Callbacks</a>.
 164     </p>
 165 <div class="warning"><table border="0" summary="Warning">
 166 <tr>
 167 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../doc/src/images/warning.png"></td>
 168 <th align="left">Warning</th>
 169 </tr>
 170 <tr><td align="left" valign="top"><p>
 171         This library is <span class="emphasis"><em>not</em></span> an official Boost library.
 172       </p></td></tr>
 173 </table></div>
 174 <p>
 175       <span class="bold"><strong>Boost.Fiber</strong></span> depends upon <a href="http://www.boost.org/doc/libs/release/libs/context/index.html" target="_top">Boost.Context</a>.
 176       Boost version 1.61.0 or greater is required.
 177     </p>
 178 <div class="note"><table border="0" summary="Note">
 179 <tr>
 180 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
 181 <th align="left">Note</th>
 182 </tr>
 183 <tr><td align="left" valign="top"><p>
 184         This library requires C++11!
 185       </p></td></tr>
 186 </table></div>
 187 </div>
 188 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 189 <td align="left"></td>
 190 <td align="right"><div class="copyright-footer">Copyright &#169; 2013 Oliver Kowalke<p>
 191         Distributed under the Boost Software License, Version 1.0. (See accompanying
 192         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>)
 193       </p>
 194 </div></td>
 195 </tr></table>
 196 <hr>
 197 <div class="spirit-nav">
 198 <a accesskey="p" href="../index.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.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 199 </div>
 200 </body>
 201 </html>