fiber

class fiber;

This class is a move-only handle representing a spawned fiber. fiber objects may also be in a state that doesn’t represent any fiber (default constructor, after move-from, detach(), or join()).

Warning
 If the object represents a valid fiber, you MUST either call join(this_fiber) or detach() before the destructor is run.
Important
 fiber is a typedef for basic_fiber<boost::asio::io_context::strand>. Strand below will refer to the template argument of the instantiation used.

Member-functions

Constructor

basic_fiber(); // (1)
template<class F, class StackAllocator = boost::context::default_stack>
basic_fiber(Strand executor, F&& f,
            StackAllocator salloc = StackAllocator()); // (2)
template<class F, class StackAllocator = boost::context::default_stack>
basic_fiber(decltype(std::declval<Strand>().context())& ctx, F&& f,
            StackAllocator salloc = StackAllocator()); // (3)
template<class F, class StackAllocator = boost::context::default_stack>
basic_fiber(basic_fiber::this_fiber this_fiber, F&& f,
            StackAllocator salloc = StackAllocator()); // (4)

  1. Default constructor. Creates an object which doesn’t represent any fiber.

  2. Spawn a fiber scheduled through executor.

  3. Spawn a fiber scheduled through Strand{ctx}.

  4. Spawn a fiber scheduled through this_fiber.get_executor().

joinable()

bool joinable() const;

Checks if the fiber object identifies an active fiber of execution.

join()

void join(this_fiber this_fiber);

template<class Strand2>
void join(typename basic_fiber<Strand2>::this_fiber this_fiber);

Suspend current fiber (i.e. this_fiber) until the fiber identified by *this finishes its execution.

Concurrently calling join() on the same fiber object from multiple fibers results in undefined behavior.

Preconditions

joinable() is true.

Postconditions

joinable() is false.

Exceptions

fiber_interrupted if this_fiber is interrupted.

Note
 If joining process is interrupted the handle remains joinable so you may perform the join() operation again (or perform other operations like interrupt() and detach()).

detach()

void detach();

Separates the fiber of execution from the fiber object, allowing execution to continue independently. Any allocated resources will be freed once the fiber exits.

Preconditions

joinable() is true.

Postconditions

joinable() is false.

interrupt()

void interrupt();

See interruption(7).

interruption_caught()

bool interruption_caught() const;

Check whether the fiber finished by normal means or by letting the fiber_interrupted exception escape its execution stack.

See interruption(7) for more.

Preconditions

Fiber has been successfully joined.

Nested types

this_fiber

See this_fiber(3).

Free functions

context_aborted()

bool context_aborted(boost::asio::io_context& ctx);

Check whether the context finished normally or abnormally. The context will be terminated when you fail to join() or detach() a joinable fiber (abnormal termination).

The context is terminated through the usual call to ctx.stop() in case you’re concerned. In addition, a std::logic_error may also be raised.