Scheduling

The fibers in a thread are coordinated by a fiber manager. Fibers trade control cooperatively, rather than preemptively: the currently-running fiber retains control until it invokes some operation that passes control to the manager. Each time a fiber suspends (or yields), the fiber manager consults a scheduler to determine which fiber will run next.

Boost.Fiber provides the fiber manager, but the scheduler is a customization point. (See Customization.)

Each thread has its own scheduler. By default, Boost.Fiber implicitly instantiates round_robin as the scheduler for each thread.

You are explicitly permitted to code your own sched_algorithm subclass, and to specify it to use_scheduling_algorithm().

void thread_fn() {
    boost::fibers::use_scheduling_algorithm< my_fiber_scheduler >();
    ...
}

A scheduler class must implement interface sched_algorithm. Boost.Fiber provides one scheduler: round_robin.

Class `sched_algorithm`

sched_algorithm is the abstract base class defining the interface that a fiber scheduler must implement.

#include <boost/fiber/algorithm.hpp>

struct sched_algorithm {
    virtual ~sched_algorithm();

    virtual void awakened( context *) noexcept = 0;

    virtual context * pick_next() noexcept = 0;

    virtual bool has_ready_fibers() const noexcept = 0;

    virtual void suspend_until( std::chrono::steady_clock::time_point const&) noexcept = 0;

    virtual void notify() noexcept = 0;
};

Member function `awakened`()

virtual void awakened( context * f) noexcept = 0;

Effects:: Informs the scheduler that fiber f is ready to run. Fiber f might be newly launched, or it might have been blocked but has just been awakened, or it might have called this_fiber::yield().
Note:: This method advises the scheduler to add fiber f to its collection of fibers ready to run. A typical scheduler implementation places f into a queue.
See also:: round_robin

Member function `pick_next`()

virtual context * pick_next() noexcept = 0;

Returns:: the fiber which is to be resumed next, or nullptr if there is no ready fiber.
Note:: This is where the scheduler actually specifies the fiber which is to run next. A typical scheduler implementation chooses the head of the ready queue.
See also:: round_robin

Member function `has_ready_fibers`()

virtual bool has_ready_fibers() const noexcept = 0;

Returns:: true if scheduler has fibers ready to run.

Member function `suspend_until`()

virtual void suspend_until( std::chrono::steady_clock::time_point const& abs_time) noexcept = 0;

Effects:: Informs the scheduler that no ready fiber will be available till time-point abs_time.

Member function `notify`()

virtual void notify() noexcept = 0;

Effects:: wake-up the scheduler, some fibers might ready.

Class `round_robin`

This class implements sched_algorithm, scheduling fibers in round-robin fashion.

#include <boost/fiber/round_robin.hpp>

class round_robin : public sched_algorithm {
    virtual void awakened( context *) noexcept;

    virtual context * pick_next() noexcept;

    virtual bool has_ready_fibers() const noexcept;

    virtual void suspend_until( std::chrono::steady_clock::time_point const&) noexcept;

    virtual void notify() noexcept;
};

Member function `awakened`()

virtual void awakened( context * f) noexcept;

Effects:: Enqueues fiber f onto a ready queue.
Throws:: Nothing.

Member function `pick_next`()

virtual context * pick_next() noexcept;

Returns:: the fiber at the head of the ready queue, or 0 if the queue is empty.
Throws:: Nothing.
Note:: Placing ready fibers onto a queue, and returning them from the head of that queue, shares the thread between ready fibers in round-robin fashion.

Member function `has_ready_fibers`()

virtual bool has_ready_fibers() const noexcept;

Returns:: true if scheduler has fibers ready to run.
Throws:: Nothing.

Member function `suspend_until`()

virtual void suspend_until( std::chrono::steady_clock::time_point const& abs_time) noexcept;

Effects:: Informs the scheduler that no ready fiber will be available till time-point abs_time. round_robin blocks in std::condition_variable::wait_until().
Throws:: Nothing.

Member function `notify`()

virtual void notify() noexcept = 0;

Effects:: wake-up the scheduler, some fibers might ready. signals round_robin via std::condition_variable::notify_all().
Throws:: Nothing.

Custom Scheduler Fiber Properties

A scheduler class directly derived from sched_algorithm can use any information available from context to implement the sched_algorithm interface. But a custom scheduler might need to track additional properties for a fiber. For instance, a priority-based scheduler would need to track a fiber's priority.

Boost.Fiber provides a mechanism by which your custom scheduler can associate custom properties with each fiber.

Class `fiber_properties`

A custom fiber properties class must be derived from fiber_properties.

#include <boost/fiber/properties.hpp>

class fiber_properties {
public:
    fiber_properties( context *) noexcept;

    virtual ~fiber_properties();

protected:
    void notify() noexcept;
};

Constructor

fiber_properties( context * f) noexcept;

Effects:: Constructs base-class component of custom subclass.
Throws:: Nothing.
Note:: Your subclass constructor must accept a context* and pass it to the base-class fiber_properties constructor.

Member function `notify`()

void notify() noexcept;

Effects:: Pass control to the custom sched_algorithm_with_properties<> subclass's sched_algorithm_with_properties::property_change() method.
Throws:: Nothing.
Note:: A custom scheduler's sched_algorithm_with_properties::pick_next() method might dynamically select from the ready fibers, or sched_algorithm_with_properties::awakened() might instead insert each ready fiber into some form of ready queue for pick_next(). In the latter case, if application code modifies a fiber property (e.g. priority) that should affect that fiber's relationship to other ready fibers, the custom scheduler must be given the opportunity to reorder its ready queue. The custom property subclass should implement an access method to modify such a property; that access method should call notify() once the new property value has been stored. This passes control to the custom scheduler's property_change() method, allowing the custom scheduler to reorder its ready queue appropriately. Use at your discretion. Of course, if you define a property which does not affect the behavior of the pick_next() method, you need not call notify() when that property is modified.

Template `sched_algorithm_with_properties<>`

A custom scheduler that depends on a custom properties class PROPS should be derived from sched_algorithm_with_properties<PROPS>. PROPS should be derived from fiber_properties.

#include <boost/fiber/algorithm.hpp>

template< typename PROPS >
struct sched_algorithm_with_properties {
    virtual void awakened( context *, PROPS &) noexcept = 0;

    virtual context * pick_next() noexcept;

    virtual bool has_ready_fibers() const noexcept;

    PROPS & properties( context *) noexcept;

    virtual void property_change( context *, PROPS &) noexcept;

    virtual fiber_properties * new_properties( context *);
};

Member function `awakened`()

virtual void awakened( context * f, PROPS & properties) noexcept;

Effects:: Informs the scheduler that fiber f is ready to run, like sched_algorithm::awakened(). Passes the fiber's associated PROPS instance.
Throws:: Nothing.
Note:: A sched_algorithm_with_properties<> subclass must override this method instead of sched_algorithm::awakened().

Member function `pick_next`()

virtual context * pick_next() noexcept;

Returns:: the fiber which is to be resumed next, or nullptr if there is no ready fiber.
Throws:: Nothing.
Note:: same as sched_algorithm::pick_next()

Member function `has_ready_fibers`()

virtual bool has_ready_fibers() const noexcept;

Returns:: the number of fibers ready to run.
Throws:: Nothing.
Note:: same as sched_algorithm::has_ready_fibers()

Member function `properties`()

PROPS& properties( context * f) noexcept;

Returns:: the PROPS instance associated with fiber f.
Throws:: Nothing.
Note:: The fiber's associated PROPS instance is already passed to sched_algorithm_with_properties::awakened() and sched_algorithm_with_properties::property_change(). However, every sched_algorithm subclass is expected to track a collection of ready context instances. This method allows your custom scheduler to retrieve the fiber_properties subclass instance for any context in its collection.

Member function `property_change`()

virtual void property_change( context * f, PROPS & properties) noexcept;

Effects:: Notify the custom scheduler of a possibly-relevant change to a property belonging to fiber f. properties contains the new values of all relevant properties.
Throws:: Nothing.
Note:: This method is only called when a custom fiber_properties subclass explicitly calls fiber_properties::notify().

Member function `new_properties`()

virtual fiber_properties * new_properties( context * f);

Returns:: A new instance of fiber_properties subclass PROPS.
Note:: By default, sched_algorithm_with_properties<>::new_properties() simply returns new PROPS(f), placing the PROPS instance on the heap. Override this method to allocate PROPS some other way. The returned fiber_properties pointer must point to the PROPS instance to be associated with fiber f.

Class `context`

While you are free to treat context* as an opaque token, certain context members may be useful to a custom scheduler implementation.

(Most context members are implementation details; most of interest are implementations of fiber methods.)

#include <boost/fiber/context.hpp>

class context {
public:
    class id;

    static context * active() noexcept;

    context( context const&) = delete;
    context & operator=( context const&) = delete;

    id get_id() const noexcept;

    void migrate( context *) noexcept;

    bool is_main_context() const noexcept;
    bool is_dispatcher_context() const noexcept;
    bool is_worker_context() const noexcept;

    bool is_terminated() const noexcept;

    bool ready_is_linked() const noexcept;
    bool remote_ready_is_linked() const noexcept;
    bool wait_is_linked() const noexcept;

    template< typename List >
    void ready_link( List &) noexcept;
    template< typename List >
    void remote_ready_link( List &) noexcept;
    template< typename List >
    void wait_link( List &) noexcept;

    void ready_unlink() noexcept;
    void remote_ready_unlink() noexcept;
    void wait_unlink() noexcept;
};

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

Static member function `active`()

static context * active() noexcept;

Returns:: Pointer to instance of current fiber.
Throws:: Nothing

Member function `get_id`()

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

Member function `migrate`()

void migrate( context * f) noexcept;

Effects:: Migrate fiber f to scheduler running *this.
Throws:: Nothing

Member function `is_main_context`()

bool is_main_context() const noexcept;

Returns:: true if *this is main context.
Throws:: Nothing
Note:: The context is associated with the "main" fiber of the thread: the one implicitly created by the thread itself, rather than one explicitly created by Boost.Fiber.

Member function `is_dispatcher_context`()

bool is_dispatcher_context() const noexcept;

Returns:: true if *this is dispatcher context.
Throws:: Nothing
Note:: The context is associated with a "dispatching" fiber, responsible for dispatching awakened fibers to scheduler's ready-queue.

Member function `is_worker_context`()

bool is_worker_context() const noexcept;

Returns:: true if *this is worker context.
Throws:: Nothing
Note:: The context is associated with the fiber created by Boost.Fiber.

Member function `is_terminated`()

bool is_terminated() const noexcept;

Returns:: true if *this is no longer an valid context.
Throws:: Nothing
Note:: The context has returned from its fiber-function and is no longer considered a an valid context.

Member function `ready_is_linked`()

bool ready_is_linked() const noexcept;

Returns:: true if *this is stored in scheduler's ready-queue.
Throws:: Nothing

Member function `remote_ready_is_linked`()

bool remote_ready_is_linked() const noexcept;

Returns:: true if *this is stored in scheduler's remote-ready-queue.
Throws:: Nothing
Note:: A context signaled as ready by another thread is always stored in scheduler's remote-ready-queue.

Member function `wait_is_linked`()

bool wait_is_linked() const noexcept;

Returns:: true if *this is stored in the wait-queue of some synchronization object.
Throws:: Nothing
Note:: The context of a fiber, waiting on an synchronization object (mutex, condition_variable etc.), is stored in the waiting-queue of that synchronization object.

Member function `ready_link`()

template< typename List >
void ready_link( List & lst) noexcept;

Effects:: Stores *this in ready-queue lst.
Throws:: Nothing
Note:: Argument lst must be double-liked list from Boost.Intrusive.

Member function `remote_ready_link`()

template< typename List >
void remote_ready_link( List & lst) noexcept;

Effects:: Stores *this in remote-ready-queue lst.
Throws:: Nothing
Note:: Argument lst must be double-liked list from Boost.Intrusive.

Member function `wait_link`()

template< typename List >
void wait_link( List & lst) noexcept;

Effects:: Stores *this in wait-queue lst.
Throws:: Nothing
Note:: Argument lst must be double-liked list from Boost.Intrusive.

Member function `ready_unlink`()

void ready_unlink() noexcept;

Effects:: Removes *this from ready-queue.
Throws:: Nothing

Member function `remote_ready_unlink`()

void remote_ready_unlink() noexcept;

Effects:: Removes *this from remote-ready-queue.
Throws:: Nothing

Member function `wait_unlink`()

void wait_unlink() noexcept;

Effects:: Removes *this from wait-queue.
Throws:: Nothing

Non-member function `operator<()`

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

Returns:: true if l.get_id() < r.get_id() is true and the implementation-defined total order of context::id values places *this before other, false otherwise.
Throws:: Nothing.