]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 1. Fiber"> | |
8 | <link rel="up" href="../index.html" title="Chapter 1. Fiber"> | |
9 | <link rel="prev" href="../index.html" title="Chapter 1. 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"><</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">></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">“<span class="quote">blocked</span>”</span> | |
112 | to <span class="quote">“<span class="quote">ready</span>”</span> on its current thread — 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<></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 © 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> |