Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
PrevUpHomeNext

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.


PrevUpHomeNext