...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
#include <boost/fiber/fiber.hpp> namespace boost { namespace fibers { class fiber { public: class id; constexpr fiber() noexcept; template< typename Fn, typename ... Args > fiber( Fn &&, Args && ...); template< typename Fn, typename ... Args > fiber(launch
, Fn &&, Args && ...); template< typenameStackAllocator
, typename Fn, typename ... Args > fiber(std::allocator_arg_t
, StackAllocator &&, Fn &&, Args && ...); template< typenameStackAllocator
, typename Fn, typename ... Args > fiber(launch
,std::allocator_arg_t
, StackAllocator &&, Fn &&, Args && ...); ~fiber(); fiber( fiber const&) = delete; fiber & operator=( fiber const&) = delete; fiber( fiber &&) noexcept; fiber & operator=( fiber &&) noexcept; void swap( fiber &) noexcept; bool joinable() const noexcept; id get_id() const noexcept; void detach(); void join(); template< typename PROPS > PROPS & properties(); }; bool operator<( fiber const&, fiber const&) noexcept; void swap( fiber &, fiber &) noexcept; template< typename SchedAlgo, typename ... Args > void use_scheduling_algorithm( Args && ...) noexcept; bool has_ready_fibers() noexcept; }}
constexpr fiber() noexcept;
Constructs a fiber
instance that refers to not-a-fiber.
this->get_id()
== fiber::id()
Nothing
template< typename Fn, typename ... Args > fiber( Fn && fn, Args && ... args); template< typename Fn, typename ... Args > fiber(launch
policy, Fn && fn, Args && ... args); template< typenameStackAllocator
, typename Fn, typename ... Args > fiber(std::allocator_arg_t
, StackAllocator && salloc, Fn && fn, Args && ... args); template< typenameStackAllocator
, typename Fn, typename ... Args > fiber(launch
policy,std::allocator_arg_t
, StackAllocator && salloc, Fn && fn, Args && ... args);
Fn
must be copyable
or movable.
fn
is copied or moved
into internal storage for access by the new fiber. If launch
is
specified (or defaulted) to post
,
the new fiber is marked “ready” and will be entered at
the next opportunity. If launch
is specified as dispatch
,
the calling fiber is suspended and the new fiber is entered immediately.
*this
refers to the newly created fiber of execution.
fiber_error
if an error
occurs.
StackAllocator
is required to allocate a stack for the internal __econtext__. If
StackAllocator
is not
explicitly passed, the default stack allocator depends on BOOST_USE_SEGMENTED_STACKS
: if defined,
you will get a segmented_stack
, else a fixedsize_stack
.
fiber( fiber && other) noexcept;
Transfers ownership of the fiber managed by other
to the newly constructed fiber
instance.
other.get_id()
== fiber::id()
and get_id()
returns the value of other.get_id()
prior to the construction
Nothing
fiber & operator=( fiber && other) noexcept;
Transfers ownership of the fiber managed by other
(if any) to *this
.
other->get_id()
== fiber::id()
and get_id()
returns the value of other.get_id()
prior to the assignment.
Nothing
~fiber();
If the fiber is fiber::joinable()
, calls std::terminate.
Destroys *this
.
The programmer must ensure that the destructor is never executed while
the fiber is still fiber::joinable()
. Even if you know
that the fiber has completed, you must still call either fiber::join()
or
fiber::detach()
before destroying the fiber
object.
joinable
()
bool joinable() const noexcept;
true
if *this
refers to a fiber of execution, which may or may not have completed;
otherwise false
.
Nothing
join
()
void join();
the fiber is fiber::joinable()
.
Waits for the referenced fiber of execution to complete.
The fiber of execution referenced on entry has completed. *this
no longer refers to any fiber of execution.
fiber_error
resource_deadlock_would_occur: if
this->get_id()
== boost::this_fiber::get_id()
. invalid_argument:
if the fiber is not fiber::joinable()
.
detach
()
void detach();
the fiber is fiber::joinable()
.
The fiber of execution becomes detached, and no longer has an associated
fiber
object.
*this
no longer refers to any fiber of execution.
fiber_error
invalid_argument: if the fiber is
not fiber::joinable()
.
get_id
()
fiber::id get_id() const noexcept;
properties
()
template< typename PROPS > PROPS & properties();
*this
refers to a fiber of execution. use_scheduling_algorithm()
has
been called from this thread with a subclass of algorithm_with_properties<>
with
the same template argument PROPS
.
a reference to the scheduler properties instance for *this
.
std::bad_cast
if use_scheduling_algorithm()
was called with a algorithm_with_properties
subclass with some other template parameter than PROPS
.
algorithm_with_properties<>
provides
a way for a user-coded scheduler to associate extended properties,
such as priority, with a fiber instance. This method allows access
to those user-provided properties.
swap
()
void swap( fiber & other) noexcept;
Exchanges the fiber of execution associated with *this
and other
,
so *this
becomes associated with the fiber formerly associated with other
, and vice-versa.
this->get_id()
returns the same value as other.get_id()
prior to the call. other.get_id()
returns the same value as this->get_id()
prior to the call.
Nothing
swap()
void swap( fiber & l, fiber & r) noexcept;
Same as l.swap( r)
.
Nothing
operator<()
bool operator<( fiber const& l, fiber const& r) noexcept;
true
if l.get_id()
< r.get_id()
is true
,
false otherwise.
Nothing.
use_scheduling_algorithm()
template< typename SchedAlgo, typename ... Args > void use_scheduling_algorithm( Args && ... args) noexcept;
Directs Boost.Fiber to use SchedAlgo
, which must be a concrete
subclass of algorithm
, as the scheduling algorithm for
all fibers in the current thread. Pass any required SchedAlgo
constructor arguments as args
.
If you want a given thread to use a non-default scheduling algorithm,
make that thread call use_scheduling_algorithm()
before any other Boost.Fiber
entry point. If no scheduler has been set for the current thread by
the time Boost.Fiber needs to use
it, the library will create a default round_robin
instance
for this thread.
Nothing
has_ready_fibers()
bool has_ready_fibers() noexcept;
true
if scheduler has
fibers ready to run.
Nothing
Can be used for work-stealing to find an idle scheduler.