[/ (C) Copyright 2007-8 Anthony Williams. (C) Copyright 2011-12 Vicente J. Botet Escriba. (C) Copyright 2013 Oliver Kowalke. 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:fiber_mgmt Fiber management] [heading Synopsis] #include namespace boost { namespace fibers { class fiber; bool operator<( fiber const& l, fiber const& r) noexcept; void swap( fiber & l, fiber & r) noexcept; template< typename SchedAlgo, typename ... Args > void use_scheduling_algorithm( Args && ... args); bool has_ready_fibers(); namespace algo { struct algorithm; template< typename PROPS > struct algorithm_with_properties; class round_robin; class shared_round_robin; }} namespace this_fiber { fibers::id get_id() noexcept; void yield(); template< typename Clock, typename Duration > void sleep_until( std::chrono::time_point< Clock, Duration > const& abs_time) template< typename Rep, typename Period > void sleep_for( std::chrono::duration< Rep, Period > const& rel_time); template< typename PROPS > PROPS & properties(); } [heading Tutorial] Each __fiber__ represents a micro-thread which will be launched and managed cooperatively by a scheduler. Objects of type __fiber__ are move-only. boost::fibers::fiber f1; // not-a-fiber void f() { boost::fibers::fiber f2( some_fn); f1 = std::move( f2); // f2 moved to f1 } [heading Launching] 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 ['std::ref] 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. struct callable { void operator()(); }; boost::fibers::fiber copies_are_safe() { callable x; return boost::fibers::fiber( x); } // x is destroyed, but the newly-created fiber has a copy, so this is OK boost::fibers::fiber oops() { callable x; return boost::fibers::fiber( std::ref( x) ); } // x is destroyed, but the newly-created fiber still has a reference // this leads to undefined behaviour The spawned __fiber__ 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. [#exceptions] [heading Exceptions] An exception escaping from the function or callable object passed to the __fiber__ constructor calls `std::terminate()`. If you need to know which exception was thrown, use __future__ or __packaged_task__. [heading Detaching] A __fiber__ can be detached by explicitly invoking the __detach__ member function. After __detach__ is called on a fiber object, that object represents __not_a_fiber__. The fiber object may then safely be destroyed. boost::fibers::fiber( some_fn).detach(); __boost_fiber__ provides a number of ways to wait for a running fiber to complete. You can coordinate even with a detached fiber using a [class_link mutex], or [class_link condition_variable], or any of the other [link synchronization synchronization objects] provided by the library. If a detached fiber is still running when the thread[s] main fiber terminates, the thread will not shut down. [heading Joining] In order to wait for a fiber to finish, the __join__ member function of the __fiber__ object can be used. __join__ will block until the __fiber__ object has completed. void some_fn() { ... } boost::fibers::fiber f( some_fn); ... f.join(); If the fiber has already completed, then __join__ returns immediately and the joined __fiber__ object becomes __not_a_fiber__. [heading Destruction] When a __fiber__ object representing a valid execution context (the fiber is __joinable__) is destroyed, the program terminates. If you intend the fiber to outlive the __fiber__ object that launched it, use the __detach__ method. { boost::fibers::fiber f( some_fn); } // std::terminate() will be called { boost::fibers::fiber f(some_fn); f.detach(); } // okay, program continues [#class_fiber_id] [heading Fiber IDs] Objects of class __fiber_id__ can be used to identify fibers. Each running __fiber__ has a unique __fiber_id__ obtainable from the corresponding __fiber__ by calling the __get_id__ member function. Objects of class __fiber_id__ 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. Each instance of __fiber_id__ either refers to some fiber, or __not_a_fiber__. Instances that refer to __not_a_fiber__ compare equal to each other, but not equal to any instances that refer to an actual fiber. The comparison operators on __fiber_id__ yield a total order for every non-equal __fiber_id__. [#class_launch] [heading Enumeration `launch`] `launch` specifies whether control passes immediately into a newly-launched fiber. enum class launch { dispatch, post }; [heading `dispatch`] [variablelist [[Effects:] [A fiber launched with `launch == dispatch` is entered immediately. In other words, launching a fiber with `dispatch` suspends the caller (the previously-running fiber) until the fiber scheduler has a chance to resume it later.]] ] [heading `post`] [variablelist [[Effects:] [A fiber launched with `launch == post` 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.]] [[Note:] [If `launch` is not explicitly specified, `post` is the default.]] ] [#class_fiber] [section:fiber Class `fiber`] #include 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( ``[link class_launch `launch`]``, Fn &&, Args && ...); template< typename __StackAllocator__, typename Fn, typename ... Args > fiber( __allocator_arg_t__, StackAllocator &&, Fn &&, Args && ...); template< typename __StackAllocator__, typename Fn, typename ... Args > fiber( ``[link class_launch `launch`]``, __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; }} [heading Default constructor] constexpr fiber() noexcept; [variablelist [[Effects:] [Constructs a __fiber__ instance that refers to __not_a_fiber__.]] [[Postconditions:] [`this->get_id() == fiber::id()`]] [[Throws:] [Nothing]] ] [#fiber_fiber] [heading Constructor] template< typename Fn, typename ... Args > fiber( Fn && fn, Args && ... args); template< typename Fn, typename ... Args > fiber( ``[link class_launch `launch`]`` policy, Fn && fn, Args && ... args); template< typename __StackAllocator__, typename Fn, typename ... Args > fiber( __allocator_arg_t__, StackAllocator && salloc, Fn && fn, Args && ... args); template< typename __StackAllocator__, typename Fn, typename ... Args > fiber( ``[link class_launch `launch`]`` policy, __allocator_arg_t__, StackAllocator && salloc, Fn && fn, Args && ... args); [variablelist [[Preconditions:] [`Fn` must be copyable or movable.]] [[Effects:] [`fn` is copied or moved into internal storage for access by the new fiber. If [class_link 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.]] [[Postconditions:] [`*this` refers to the newly created fiber of execution.]] [[Throws:] [__fiber_error__ if an error occurs.]] [[Note:] [__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__.]] [[See also:] [__allocator_arg_t__, [link stack Stack allocation]]] ] [heading Move constructor] fiber( fiber && other) noexcept; [variablelist [[Effects:] [Transfers ownership of the fiber managed by `other` to the newly constructed __fiber__ instance.]] [[Postconditions:] [`other.get_id() == fiber::id()` and `get_id()` returns the value of `other.get_id()` prior to the construction]] [[Throws:] [Nothing]] ] [heading Move assignment operator] fiber & operator=( fiber && other) noexcept; [variablelist [[Effects:] [Transfers ownership of the fiber managed by `other` (if any) to `*this`.]] [[Postconditions:] [`other->get_id() == fiber::id()` and `get_id()` returns the value of `other.get_id()` prior to the assignment.]] [[Throws:] [Nothing]] ] [heading Destructor] ~fiber(); [variablelist [[Effects:] [If the fiber is __joinable__, calls std::terminate. Destroys `*this`.]] [[Note:] [The programmer must ensure that the destructor is never executed while the fiber is still __joinable__. Even if you know that the fiber has completed, you must still call either __join__ or __detach__ before destroying the `fiber` object.]] ] [member_heading fiber..joinable] bool joinable() const noexcept; [variablelist [[Returns:] [`true` if `*this` refers to a fiber of execution, which may or may not have completed; otherwise `false`.]] [[Throws:] [Nothing]] ] [member_heading fiber..join] void join(); [variablelist [[Preconditions:] [the fiber is __joinable__.]] [[Effects:] [Waits for the referenced fiber of execution to complete.]] [[Postconditions:] [The fiber of execution referenced on entry has completed. `*this` no longer refers to any fiber of execution.]] [[Throws:] [`fiber_error`]] [[Error Conditions:] [ [*resource_deadlock_would_occur]: if `this->get_id() == boost::this_fiber::get_id()`. [*invalid_argument]: if the fiber is not __joinable__.]] ] [member_heading fiber..detach] void detach(); [variablelist [[Preconditions:] [the fiber is __joinable__.]] [[Effects:] [The fiber of execution becomes detached, and no longer has an associated __fiber__ object.]] [[Postconditions:] [`*this` no longer refers to any fiber of execution.]] [[Throws:] [`fiber_error`]] [[Error Conditions:] [ [*invalid_argument]: if the fiber is not __joinable__.]] ] [member_heading fiber..get_id] fiber::id get_id() const noexcept; [variablelist [[Returns:] [If `*this` refers to a fiber of execution, an instance of __fiber_id__ that represents that fiber. Otherwise returns a default-constructed __fiber_id__.]] [[Throws:] [Nothing]] [[See also:] [[ns_function_link this_fiber..get_id]]] ] [template_member_heading fiber..properties] template< typename PROPS > PROPS & properties(); [variablelist [[Preconditions:] [`*this` refers to a fiber of execution. [function_link use_scheduling_algorithm] has been called from this thread with a subclass of [template_link algorithm_with_properties] with the same template argument `PROPS`.]] [[Returns:] [a reference to the scheduler properties instance for `*this`.]] [[Throws:] [`std::bad_cast` if `use_scheduling_algorithm()` was called with a `algorithm_with_properties` subclass with some other template parameter than `PROPS`.]] [[Note:] [[template_link 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.]] [[See also:] [[link custom Customization]]] ] [member_heading fiber..swap] void swap( fiber & other) noexcept; [variablelist [[Effects:] [Exchanges the fiber of execution associated with `*this` and `other`, so `*this` becomes associated with the fiber formerly associated with `other`, and vice-versa.]] [[Postconditions:] [`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.]] [[Throws:] [Nothing]] ] [function_heading_for swap..fiber] void swap( fiber & l, fiber & r) noexcept; [variablelist [[Effects:] [Same as `l.swap( r)`.]] [[Throws:] [Nothing]] ] [function_heading operator<] bool operator<( fiber const& l, fiber const& r) noexcept; [variablelist [[Returns:] [`true` if `l.get_id() < r.get_id()` is `true`, false otherwise.]] [[Throws:] [Nothing.]] ] [function_heading use_scheduling_algorithm] template< typename SchedAlgo, typename ... Args > void use_scheduling_algorithm( Args && ... args) noexcept; [variablelist [[Effects:] [Directs __boost_fiber__ to use `SchedAlgo`, which must be a concrete subclass of __algo__, as the scheduling algorithm for all fibers in the current thread. Pass any required `SchedAlgo` constructor arguments as `args`.]] [[Note:] [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 [class_link round_robin] instance for this thread.]] [[Throws:] [Nothing]] [[See also:] [[link scheduling Scheduling], [link custom Customization]]] ] [function_heading has_ready_fibers] bool has_ready_fibers() noexcept; [variablelist [[Returns:] [`true` if scheduler has fibers ready to run.]] [[Throws:] [Nothing]] [[Note:] [Can be used for work-stealing to find an idle scheduler.]] ] [endsect] [/ section Class fiber] [#class_id] [section:id Class fiber::id] #include namespace boost { namespace fibers { class id { public: constexpr id() noexcept; bool operator==( id const&) const noexcept; bool operator!=( id const&) const noexcept; bool operator<( id const&) const noexcept; bool operator>( id const&) const noexcept; bool operator<=( id const&) const noexcept; bool operator>=( id const&) const noexcept; template< typename charT, class traitsT > friend std::basic_ostream< charT, traitsT > & operator<<( std::basic_ostream< charT, traitsT > &, id const&); }; }} [heading Constructor] constexpr id() noexcept; [variablelist [[Effects:] [Represents an instance of __not_a_fiber__.]] [[Throws:] [Nothing.]] ] [operator_heading id..operator_equal..operator==] bool operator==( id const& other) const noexcept; [variablelist [[Returns:] [`true` if `*this` and `other` represent the same fiber, or both represent __not_a_fiber__, `false` otherwise.]] [[Throws:] [Nothing.]] ] [operator_heading id..operator_not_equal..operator!=] bool operator!=( id const& other) const noexcept; [variablelist [[Returns:] [[`! (other == * this)]]] [[Throws:] [Nothing.]] ] [operator_heading id..operator_less..operator<] bool operator<( id const& other) const noexcept; [variablelist [[Returns:] [`true` if `*this != other` is true and the implementation-defined total order of `fiber::id` values places `*this` before `other`, false otherwise.]] [[Throws:] [Nothing.]] ] [operator_heading id..operator_greater..operator>] bool operator>( id const& other) const noexcept; [variablelist [[Returns:] [`other < * this`]] [[Throws:] [Nothing.]] ] [operator_heading id..operator_less_equal..operator<=] bool operator<=( id const& other) const noexcept; [variablelist [[Returns:] [`! (other < * this)`]] [[Throws:] [Nothing.]] ] [operator_heading id..operator_greater_equal..operator>=] bool operator>=( id const& other) const noexcept; [variablelist [[Returns:] [`! (* this < other)`]] [[Throws:] [Nothing.]] ] [heading operator<<] template< typename charT, class traitsT > std::basic_ostream< charT, traitsT > & operator<<( std::basic_ostream< charT, traitsT > & os, id const& other); [variablelist [[Efects:] [Writes the representation of `other` to stream `os`. The representation is unspecified.]] [[Returns:] [`os`]] ] [endsect] [/ section Class fiber::id] [section:this_fiber Namespace this_fiber] In general, `this_fiber` operations may be called from the ["main] fiber [mdash] the fiber on which function `main()` is entered [mdash] as well as from an explicitly-launched thread[s] thread-function. That is, in many respects the main fiber on each thread can be treated like an explicitly-launched fiber. namespace boost { namespace this_fiber { fibers::fiber::id get_id() noexcept; void yield() noexcept; template< typename Clock, typename Duration > void sleep_until( std::chrono::time_point< Clock, Duration > const&); template< typename Rep, typename Period > void sleep_for( std::chrono::duration< Rep, Period > const&); template< typename PROPS > PROPS & properties(); }} [ns_function_heading this_fiber..get_id] #include namespace boost { namespace fibers { fiber::id get_id() noexcept; }} [variablelist [[Returns:] [An instance of __fiber_id__ that represents the currently executing fiber.]] [[Throws:] [Nothing.]] ] [ns_function_heading this_fiber..sleep_until] #include namespace boost { namespace fibers { template< typename Clock, typename Duration > void sleep_until( std::chrono::time_point< Clock, Duration > const& abs_time); }} [variablelist [[Effects:] [Suspends the current fiber until the time point specified by `abs_time` has been reached.]] [[Throws:] [timeout-related exceptions.]] [[Note:] [The current fiber will not resume before `abs_time`, but there are no guarantees about how soon after `abs_time` it might resume.]] [[Note:] [["timeout-related exceptions] are as defined in the C++ Standard, section [*30.2.4 Timing specifications \[thread.req.timing\]]: ["A function that takes an argument which specifies a timeout will throw if, during its execution, a clock, time point, or time duration throws an exception. Such exceptions are referred to as ['timeout-related exceptions.]]]] ] [ns_function_heading this_fiber..sleep_for] #include namespace boost { namespace fibers { template< class Rep, class Period > void sleep_for( std::chrono::duration< Rep, Period > const& rel_time); }} [variablelist [[Effects:] [Suspends the current fiber until the time duration specified by `rel_time` has elapsed.]] [[Throws:] [timeout-related exceptions.]] [[Note:][The current fiber will not resume before `rel_time` has elapsed, but there are no guarantees about how soon after that it might resume.]] ] [ns_function_heading this_fiber..yield] #include namespace boost { namespace fibers { void yield() noexcept; }} [variablelist [[Effects:] [Relinquishes execution control, allowing other fibers to run.]] [[Throws:] [Nothing.]] [[Note:] [A fiber that calls `yield()` is not suspended: it is immediately passed to the scheduler as ready to run.]] ] [ns_function_heading this_fiber..properties] #include namespace boost { namespace fibers { template< typename PROPS > PROPS & properties(); }} [variablelist [[Preconditions:] [[function_link use_scheduling_algorithm] has been called from this thread with a subclass of [template_link algorithm_with_properties] with the same template argument `PROPS`.]] [[Returns:] [a reference to the scheduler properties instance for the currently running fiber.]] [[Throws:] [`std::bad_cast` if `use_scheduling_algorithm()` was called with an `algorithm_with_properties` subclass with some other template parameter than `PROPS`.]] [[Note:] [[template_link algorithm_with_properties] provides a way for a user-coded scheduler to associate extended properties, such as priority, with a fiber instance. This function allows access to those user-provided properties.]] [[Note:] [The first time this function is called from the main fiber of a thread, it may internally yield, permitting other fibers to run.]] [[See also:] [[link custom Customization]]] ] [endsect] [/ section Namespace this_fiber] [endsect] [/ section Fiber Management]