SchedulerCommutator Class Reference

#include "vault/gear/scheduler-commutator.hpp"

Description

Scheduler Layer-2 : execution of Scheduler Activities.

• protect data structures through exclusive »grooming mode«
• use the underlying Layer-1 to retrieve the most urgent work
• dispatch and execute a chain of Render Activities

  See also

  SchedulerInvocation (Layer-1)

  SchedulerCommutator_test

Definition at line 109 of file scheduler-commutator.hpp.

Public Member Functions
bool	acquireGoomingToken () noexcept
	acquire the right to perform internal state transitions. More...
template<class DISPATCH , class CLOCK >
activity::Proc	dispatchCapacity (SchedulerInvocation &, LoadController &, DISPATCH, CLOCK)
	Implementation of the worker-Functor: More...
void	dropGroomingToken () noexcept
	relinquish the right for internal state transitions. More...
ActivationEvent	findWork (SchedulerInvocation &layer1, Time now)
	Look into the queues and possibly retrieve work due by now. More...
bool	holdsGroomingToken (ThreadID id) noexcept
	check if the indicated thread currently holds the right to conduct internal state transitions.
bool	maintainQueueHead (SchedulerInvocation &layer1, Time now)
	update queue head to discard obsolete content. More...
void	maybeFeed (SchedulerInvocation &layer1)
	tend to the input queue if possible
activity::Proc	postChain (ActivationEvent event, SchedulerInvocation &layer1)
	This is the primary entrance point to the Scheduler. More...
ScopedGroomingGuard	requireGroomingTokenHere ()
	a scope guard to force acquisition of the GroomingToken More...

Classes
class	ScopedGroomingGuard
struct	WorkerInstruction
	monad-like step sequence: perform sequence of steps, as long as the result remains activity::PASS More...

Private Types
using	ThreadID = std::thread::id

Private Member Functions
void	ensureDroppedGroomingToken ()
activity::Proc	scatteredDelay (Time now, Time head, LoadController &loadController, LoadController::Capacity capacity)
	A worker asking for work constitutes free capacity, which can be redirected into a focused zone of the scheduler time axis where it is most likely to be useful, unless there is active work to be carried out right away. More...
Private Member Functions inherited from NonCopyable
	NonCopyable (NonCopyable const &)=delete
NonCopyable &	operator= (NonCopyable const &)=delete

Private Attributes
atomic< ThreadID >	groomingToken_ {}

Member Function Documentation

acquireGoomingToken()

bool acquireGoomingToken ( )

inlinenoexcept

acquire the right to perform internal state transitions.

Returns

true if this attempt succeeded

Note

only one thread at a time can acquire the GoomingToken successfully.

Remarks

only if testing and branching on the return value, this also constitutes a valid sync barrier; in this case you can be sure to see the real values of any scheduler internals and are free to manipulate.

Definition at line 128 of file scheduler-commutator.hpp.

References vault::gear::anonymous_namespace{scheduler-commutator.hpp}::thisThread().

Referenced by SchedulerCommutator_test::___ensureGroomingTokenReleased(), SchedulerCommutator_test::blockGroomingToken(), SchedulerCommutator::findWork(), SchedulerCommutator::maybeFeed(), SchedulerCommutator::scatteredDelay(), and SchedulerCommutator_test::verify_postChain().

Here is the call graph for this function:

Here is the caller graph for this function:

dropGroomingToken()

void dropGroomingToken ( )

inlinenoexcept

relinquish the right for internal state transitions.

Remarks

any changes done to scheduler internals prior to this call will be sequenced-before anything another thread does later, bot only if the other thread first successfully acquires the GroomingToken.

Definition at line 144 of file scheduler-commutator.hpp.

References vault::gear::anonymous_namespace{scheduler-commutator.hpp}::thisThread().

Referenced by SchedulerCommutator_test::___ensureGroomingTokenReleased(), SchedulerCommutator_test::blockGroomingToken(), SchedulerCommutator_test::integratedWorkCycle(), SchedulerCommutator::postChain(), SchedulerCommutator::ScopedGroomingGuard::ScopedGroomingGuard(), SchedulerCommutator_test::verify_postChain(), and Scheduler::ExecutionCtx::work().

Here is the call graph for this function:

Here is the caller graph for this function:

requireGroomingTokenHere()

SchedulerCommutator::ScopedGroomingGuard requireGroomingTokenHere ( )

inline

a scope guard to force acquisition of the GroomingToken

Warning

this provides very specific functionality required by the »Scheduler Service« to handle both external and internal calls properly.

• whenever a thread already holds the GroomingToken, no further action is performed (so the cost of this feature is one additional atomic read on the token)
• however, a thread coming from the outside and not belonging to the Scheduler ecosystem is typically not aware of the GroomingToken altogether. The token is acquired, possibly incurring a blocking wait, and it is dropped transparently when leaving the scope.

Definition at line 464 of file scheduler-commutator.hpp.

Referenced by Scheduler::handleDutyCycle(), SchedulerCommutator::holdsGroomingToken(), Scheduler::seedCalcStream(), and SchedulerCommutator_test::verify_GroomingGuard().

Here is the caller graph for this function:

maintainQueueHead()

bool maintainQueueHead ( SchedulerInvocation &  layer1, Time  now  )

inline

update queue head to discard obsolete content.

Parameters

now	current time to use for decision about dropping tasks

Returns

false when failing to establish a consistent state due to missed compulsory entries; should cause Emergency halt.

Definition at line 184 of file scheduler-commutator.hpp.

References SchedulerInvocation::feedPrioritisation(), SchedulerCommutator::holdsGroomingToken(), SchedulerInvocation::isOutdated(), SchedulerInvocation::isOutOfTime(), SchedulerInvocation::pullHead(), and vault::gear::anonymous_namespace{scheduler-commutator.hpp}::thisThread().

Referenced by SchedulerCommutator::findWork(), and Scheduler::handleDutyCycle().

Here is the call graph for this function:

Here is the caller graph for this function:

findWork()

ActivationEvent findWork ( SchedulerInvocation &  layer1, Time  now  )

inline

Look into the queues and possibly retrieve work due by now.

Note

transparently discards any outdated entries, but blocks if a compulsory entry becomes outdated.

Definition at line 199 of file scheduler-commutator.hpp.

References SchedulerCommutator::acquireGoomingToken(), SchedulerInvocation::feedPrioritisation(), SchedulerCommutator::holdsGroomingToken(), SchedulerInvocation::isOutdated(), SchedulerInvocation::isOutOfTime(), SchedulerCommutator::maintainQueueHead(), SchedulerInvocation::pullHead(), and vault::gear::anonymous_namespace{scheduler-commutator.hpp}::thisThread().

Referenced by SchedulerCommutator_test::demonstrateSimpleUsage(), SchedulerCommutator::dispatchCapacity(), SchedulerCommutator_test::integratedWorkCycle(), SchedulerCommutator_test::verify_findWork(), SchedulerCommutator_test::verify_postChain(), and SchedulerCommutator_test::verify_Significance().

Here is the call graph for this function:

Here is the caller graph for this function:

postChain()

activity::Proc postChain ( ActivationEvent  event, SchedulerInvocation &  layer1  )

inline

This is the primary entrance point to the Scheduler.

Place the given event into the schedule, with prioritisation according to its start time.

Parameters

event

the chain of Render Activities to be scheduled, including start time and deadline

Returns

Status value to indicate how to proceed processing

• activity::PASS continue processing in regular operation
• activity::WAIT nothing to do now, check back later
• activity::HALT serious problem, cease processing

Note

Never attempts to acquire the GroomingToken itself, but if current thread holds the token, the task can be placed directly into the scheduler queue.

Definition at line 233 of file scheduler-commutator.hpp.

References SchedulerCommutator::dispatchCapacity(), SchedulerCommutator::dropGroomingToken(), SchedulerInvocation::feedPrioritisation(), SchedulerCommutator::holdsGroomingToken(), SchedulerInvocation::instruct(), SchedulerCommutator::scatteredDelay(), and vault::gear::anonymous_namespace{scheduler-commutator.hpp}::thisThread().

Referenced by Scheduler::handleDutyCycle(), SchedulerCommutator_test::integratedWorkCycle(), Scheduler::ExecutionCtx::post(), Scheduler::postChain(), and SchedulerCommutator_test::verify_postChain().

Here is the call graph for this function:

Here is the caller graph for this function:

dispatchCapacity()

activity::Proc dispatchCapacity ( SchedulerInvocation &  layer1, LoadController &  loadController, DISPATCH  executeActivity, CLOCK  getSchedTime  )

inline

Implementation of the worker-Functor:

• redirect work capacity in accordance to current scheduler and load
• dequeue and dispatch the Activity chains from the queue to perform the render jobs.

Remarks

this function is invoked from within the worker thread(s) and will

• decide if and how the capacity of this worker shall be used right now
• possibly go into a short targeted wait state to redirect capacity at a better time point
• and most notably commence with dispatch of render Activities, to calculate media data.

Returns

an instruction for the work::Worker how to proceed next:

• activity::PASS causes the worker to poll again immediately
• activity::KICK to contend (spin) on GroomingToken
• activity::WAIT induces a sleep state
• activity::HALT terminates the worker

Note

Under some circumstances, this function depends on acquiring the »grooming-token«, which is an atomic lock to ensure only one thread at a time can alter scheduler internals. In the regular processing sequence, this token is dropped after dequeuing and processing some Activities, yet prior to invoking the actual »Render Job«. Explicitly dropping the token at the end of this function is a safeguard against deadlocking the system. If some other thread happens to hold the token, SchedulerCommutator::findWork will bail out, leading to active spinning wait for the current thread.

Definition at line 320 of file scheduler-commutator.hpp.

References SchedulerCommutator::findWork(), SchedulerInvocation::headTime(), LoadController::markIncomingCapacity(), LoadController::markOutgoingCapacity(), SchedulerCommutator::maybeFeed(), and SchedulerCommutator::scatteredDelay().

Referenced by Scheduler::doWork(), SchedulerCommutator::postChain(), and SchedulerCommutator_test::verify_dispatch().

Here is the call graph for this function:

Here is the caller graph for this function:

scatteredDelay()

activity::Proc scatteredDelay ( Time  now, Time  head, LoadController &  loadController, LoadController::Capacity  capacity  )

inlineprivate

A worker asking for work constitutes free capacity, which can be redirected into a focused zone of the scheduler time axis where it is most likely to be useful, unless there is active work to be carried out right away.

Parameters

capacity

classification of the capacity to employ this thread

Returns

how to proceed further with this worker

• activity::PASS indicates to proceed or call back immediately
• activity::SKIP causes to exit this round, yet call back again
• activity::KICK signals contention (not emitted here)
• activity::WAIT exits and places the worker into sleep mode

Note

as part of the regular work processing, this function may place the current thread into a short-term targeted sleep.

Definition at line 377 of file scheduler-commutator.hpp.

References SchedulerCommutator::acquireGoomingToken(), LoadController::DISPATCH, SchedulerCommutator::holdsGroomingToken(), LoadController::IDLEWAIT, LoadController::scatteredDelayTime(), LoadController::SPINTIME, LoadController::tendedNext(), LoadController::tendNext(), LoadController::TENDNEXT, and vault::gear::anonymous_namespace{scheduler-commutator.hpp}::thisThread().

Referenced by SchedulerCommutator::dispatchCapacity(), and SchedulerCommutator::postChain().

Here is the call graph for this function:

Here is the caller graph for this function:

Inheritance diagram for SchedulerCommutator:

Collaboration diagram for SchedulerCommutator:

---

The documentation for this class was generated from the following file:

• scheduler-commutator.hpp