Class fiber - 1.86.0

Class `fiber`

#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< typename StackAllocator, typename Fn, typename ... Args >
    fiber( std::allocator_arg_t, StackAllocator &&, Fn &&, Args && ...);

    template< typename StackAllocator, 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;

}}

Default constructor

constexpr fiber() noexcept;

Effects:: Constructs a fiber instance that refers to not-a-fiber.
Postconditions:: this->get_id() == fiber::id()
Throws:: Nothing

Constructor

template< typename Fn, typename ... Args >
fiber( Fn && fn, Args && ... args);

template< typename Fn, typename ... Args >
fiber( launch policy, Fn && fn, Args && ... args);

template< typename StackAllocator, typename Fn, typename ... Args >
fiber( std::allocator_arg_t, StackAllocator && salloc, Fn && fn, Args && ... args);

template< typename StackAllocator, typename Fn, typename ... Args >
fiber( launch policy, std::allocator_arg_t, StackAllocator && salloc,
       Fn && fn, Args && ... args);

Preconditions:: Fn must be copyable or movable.
Effects:: 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.
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:: std::allocator_arg_t, Stack allocation

Move constructor

fiber( fiber && other) noexcept;

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

Move assignment operator

fiber & operator=( fiber && other) noexcept;

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

Destructor

~fiber();

Effects:: If the fiber is fiber::joinable(), calls std::terminate. Destroys *this.
Note:: 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.

Member function `joinable`()

bool joinable() const noexcept;

Returns:: true if *this refers to a fiber of execution, which may or may not have completed; otherwise false.
Throws:: Nothing

Member function `join`()

void join();

Preconditions:: the fiber is fiber::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 fiber::joinable().

Member function `detach`()

void detach();

Preconditions:: the fiber is fiber::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 fiber::joinable().

Member function `get_id`()

fiber::id get_id() const noexcept;

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:: this_fiber::get_id()

Templated member function `properties`()

template< typename PROPS >
PROPS & properties();

Preconditions:: *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.
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:: 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:: Customization

Member function `swap`()

void swap( fiber & other) noexcept;

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

Non-member function `swap()`

void swap( fiber & l, fiber & r) noexcept;

Effects:: Same as l.swap( r).
Throws:: Nothing

Non-member function `operator<()`

bool operator<( fiber const& l, fiber const& r) noexcept;

Returns:: true if l.get_id() < r.get_id() is true, false otherwise.
Throws:: Nothing.

Non-member function `use_scheduling_algorithm()`

template< typename SchedAlgo, typename ... Args >
void use_scheduling_algorithm( Args && ... args) noexcept;

Effects:: 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.
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 round_robin instance for this thread.
Throws:: Nothing
See also:: Scheduling, Customization

Non-member function `has_ready_fibers()`

bool has_ready_fibers() noexcept;

Returns:: true if scheduler has fibers ready to run.
Throws:: Nothing
Note:: Can be used for work-stealing to find an idle scheduler.