Class fiber

| Home | Libraries | People | FAQ | More

### 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.