mirror of
https://github.com/boostorg/fiber.git
synced 2026-02-17 01:32:32 +00:00
d653cbdcc6
Add a note to the condition_variable::wait_for(..., pred) overload. fiber_specific_ptr::reset() has no default argument. Remove mention of launch policy deferred, since no API accepts a launch policy argument. Copy construction or copy assignment of a shared_future leaves other.valid() unchanged. It won't be 'true' unless it was 'true' before. Mention that [shared_]future::get_exception_ptr() does not invalidate. Note that 'blocks' and 'suspends' are used interchangeably. Add some cross-references; add link to std::allocator_arg_t. Clarify the cross-reference to the paragraph describing BOOST_FIBERS_NO_ATOMICS. Reformat some overly-long source lines.
114 lines
4.9 KiB
Plaintext
114 lines
4.9 KiB
Plaintext
[/
|
|
Copyright Oliver Kowalke 2013.
|
|
Distributed under the Boost Software License, Version 1.0.
|
|
(See accompanying file LICENSE_1_0.txt or copy at
|
|
http://www.boost.org/LICENSE_1_0.txt
|
|
]
|
|
|
|
[section:overview Overview]
|
|
|
|
__boost_fiber__ provides a framework for micro-/userland-threads (fibers)
|
|
scheduled cooperatively.
|
|
The API contains classes and functions to manage and synchronize fibers similiarly to
|
|
__boost_thread__.
|
|
|
|
Each fiber has its own stack.
|
|
|
|
A fiber can save the current execution state, including all registers
|
|
and CPU flags, the instruction pointer, and the stack pointer and later restore
|
|
this state.
|
|
The idea is to have multiple execution paths running on a single thread using
|
|
cooperative scheduling (versus threads, which are preemptively scheduled). The
|
|
running fiber decides explicitly when it should yield to allow another fiber to
|
|
run (context switching).
|
|
__boost_fiber__ internally uses __econtext__ from __boost_context__; the classes in
|
|
this library manage, schedule and, when needed, synchronize those execution contexts.
|
|
A context switch between threads usually costs thousands of CPU cycles on x86,
|
|
compared to a fiber switch with less than a hundred cycles.
|
|
A fiber can only run on a single thread at any point in time.
|
|
|
|
In order to use the classes and functions described here, you can either include
|
|
the specific headers specified by the descriptions of each class or function, or
|
|
include the master library header:
|
|
|
|
#include <boost/fiber/all.hpp>
|
|
|
|
which includes all the other headers in turn.
|
|
|
|
The namespaces used are:
|
|
|
|
namespace boost::fibers
|
|
namespace boost::this_fiber
|
|
|
|
[heading Fibers and Threads]
|
|
|
|
Control is cooperatively passed between fibers launched on a given thread. At
|
|
a given moment, on a given thread, at most one fiber is running.
|
|
|
|
Spawning additional fibers on a given thread does not increase your program's
|
|
utilization of hardware cores.
|
|
|
|
On the other hand, a fiber may safely access any resource exclusively owned by
|
|
its parent thread without explicitly needing to defend that resource against
|
|
concurrent access by other fibers on the same thread. You are already
|
|
guaranteed that no other fiber on that thread is concurrently touching that
|
|
resource. This can be particularly important when introducing concurrency in
|
|
legacy code. You can safely spawn fibers running old code, using asynchronous
|
|
I/O to interleave execution.
|
|
|
|
In effect, fibers provide a natural way to organize concurrent code based on
|
|
asynchronous I/O. Instead of chaining together completion handlers, code
|
|
running on a fiber can make what looks like a normal blocking function call.
|
|
That call can cheaply suspend the calling fiber, allowing other fibers on the
|
|
same thread to run. When the operation has completed, the suspended fiber
|
|
resumes, without having to explicitly save or restore its state. Its local
|
|
stack variables persist across the call.
|
|
|
|
A fiber launched on a particular thread will always run on that thread. A
|
|
fiber can count on thread-local storage; however that storage will be shared
|
|
among all fibers running on the same thread.
|
|
|
|
[#cross_thread_sync]
|
|
[heading BOOST_FIBERS_NO_ATOMICS]
|
|
The fiber synchronization objects provided by this library will, by default,
|
|
safely synchronize fibers running on different threads. However, this level of
|
|
synchronization can be removed (for performance) by building the library with
|
|
[*`BOOST_FIBERS_NO_ATOMICS`] defined. When the library is built with that macro,
|
|
you must ensure that all the fibers referencing a particular synchronization
|
|
object are running in the same thread. Please see [link synchronization
|
|
Synchronization].
|
|
|
|
For fiber-local storage, please see __fsp__.
|
|
|
|
[#blocking]
|
|
[heading Blocking]
|
|
|
|
Normally, when this documentation states that a particular fiber ['blocks] (or
|
|
equivalently, ['suspends),] it means that it yields control, allowing other
|
|
fibers on the same thread to run. The synchronization mechanisms provided by
|
|
__boost_fiber__ have this behavior.
|
|
|
|
A fiber may, of course, use normal thread synchronization mechanisms; however
|
|
a fiber that invokes any of these mechanisms will block its entire thread,
|
|
preventing any other fiber from running on that thread in the meantime. For
|
|
instance, when a fiber wants to wait for a value from another fiber in the
|
|
same thread, using `std::future` would be unfortunate: `std::future::get()` would
|
|
block the whole thread, preventing the other fiber from delivering its value.
|
|
Use __future__ instead.
|
|
|
|
Similarly, a fiber that invokes a normal blocking I/O operation will block its
|
|
entire thread. Fiber authors are encouraged to consistently use asynchronous
|
|
I/O. __boost_asio__ and other asynchronous I/O operations can
|
|
straightforwardly be adapted for __boost_fiber__: see [link callbacks
|
|
Integrating Fibers with Asynchronous Callbacks].
|
|
|
|
[warning This library is ['not] an official Boost library.]
|
|
|
|
__boost_fiber__ depends upon __boost_context__.
|
|
Boost version 1.58.0 or greater is required.
|
|
|
|
[note This library is C++14-only!]
|
|
|
|
|
|
[endsect]
|