This illustrates use of a sched_algorithm_with_properties<PROPS> subclass that
defines, and supports, a priority property. The example includes a (somewhat
contrived) case in which a fiber must be moved within the scheduler's ready
queue due to a priority change.
Every sched_algorithm_with_properties<PROPS> subclass awakened() call must
ensure that control reaches sched_algorithm_with_properties<PROPS>::awakened()
_before_ any logic in the subclass method attempts to access properties. This
turns out to be all too easy to forget.
So instead, advise subclasses to overrride new awakened_props() method. Base-
class method sets things up and then calls awakened_props(). Moreover, when
the compiler supports it, sched_algorithm_with_properties<PROPS>::awakened()
is now marked 'final' to remind subclass authors to override awakened_props()
instead.
Priority is another property that's only relevant for future sched_algorithm
implementations. We don't even have an example yet. It's a good candidate for
moving to a specific fiber_properties subclass for that specific
sched_algorithm implementation.
thread_affinity is a good example of a property relevant only to a particular
sched_algorithm implementation. In examples/cpp03/migration, introduce an
'affinity' subclass of fiber_properties with a thread_affinity data
member.
Derive workstealing_round_robin from sched_algorithm_with_properties<affinity>
and, as required by that base class, forward awakened() calls to base-class
awakened() method.
Reimplement workstealing_round_robin's queue from a std::deque to a "by hand"
intrusive singly-linked list so we can efficiently remove an arbitrary item.
Make steal() method, instead of always popping the last item, scan the list to
find the last item willing to migrate (! thread_affinity).
From examples/cpp03/migration/workstealing_round_robin.hpp, an example of a
user-supplied sched_algorithm implementation, remove all boost/fiber/detail
#includes. These should no longer be needed.
Change sched_algorithm_with_properties::properties(worker_fiber*) method to
accept fiber_base* instead. The original signature was introduced when every
sched_algorithm implementation necessarily manipulated worker_fiber* pointers.
Now we're intentionally avoiding the need.
For the same reason, introduce a fiber_properties::back_ptr typedef so
subclasses can opaquely pass such pointers through their own constructor to
the base-class constructor.
Some reviewers disliked that to build a custom sched_algorithm subclass, you
must necessarily manipulate pointers to classes in the boost::fibers::detail
namespace. Redefine all such methods to use fiber_base* rather than
detail::worker_fiber*.
Hoist fiber_base* into boost::fibers namespace. We considered an opaque
typedef rather than fiber_base*, but in fact a sched_algorithm subclass may
need is_ready().
Moreover, a sched_algorithm subclass may well want to use an intrusive linked
list to queue fibers. Hoist worker_fiber::nxt_ pointer into fiber_base, and
remove worker_fiber::next() and next_reset() methods. This allows recasting
detail::fifo in terms of fiber_base*, therefore round_robin can be stated
almost entirely in terms of fiber_base* rather than worker_fiber*.
Recast fiber constructor taking worker_fiber* to take fiber_base* instead.
This constructor is used solely for fiber migration; with relevant functions
now returning fiber_base*, we think we no longer need fiber(worker_fiber*).
Introduce fiber_properties class from which to derive a specific properties
class for a particular user-coded sched_algorithm subclass.
Add sched_algorithm::property_change(worker_fiber*, fiber_properties*) method
to allow a fiber_properties subclass method to notify the sched_algorithm
subclass of a change in a relevant property. This generalizes the present
priority() method.
Introduce sched_algorithm_with_properties<PROPS> template class from which to
derive a user-coded scheduler that uses fiber_properties subclass PROPS. Give
it ref-returning properties(fiber::id) and properties(worker_fiber*) methods.
Introduce fiber_properties* field in worker_fiber, and initialize it to 0.
Delete it when the worker_fiber is destroyed. Give it pointer-flavored access
methods. Normally this field will remain 0; but the first time the
worker_fiber is passed to a sched_algorithm_with_properties<PROPS> subclass,
its awakened() method will instantiate the relevant PROPS subclass.
Add ref-returning fiber::properties<PROPS>() method. Calling this method
presumes that the current thread's sched_algorithm is derived from
sched_algorithm_with_properties<PROPS>.
Also add this_fiber::properties<PROPS>() with the same restriction.
Add ref-returning fm_properties<PROPS>() functions to implement
fiber::properties<PROPS>() and this_fiber::properties<PROPS>().
Allow sched_algorithm_with_properties to extract the worker_fiber* from a
fiber::id (aka worker_fiber::id) so it can present public-facing
properties(id) method as well as properties(worker_fiber*) method.
(cherry picked from commit 18c7f2c13b9642826b42aa3f6fa0a6642fce9cbc)
Conflicts:
include/boost/fiber/detail/worker_fiber.hpp
include/boost/fiber/fiber_manager.hpp
