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 107 of file scheduler-commutator.hpp.

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

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

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

Private Member Functions
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.
void	ensureDroppedGroomingToken ()
Private Member Functions inherited from NonCopyable
	~NonCopyable ()=default
	NonCopyable ()=default
	NonCopyable (NonCopyable const &)=delete
NonCopyable &	operator= (NonCopyable const &)=delete

Private Attributes
atomic< ThreadID >	groomingToken_ {}

Constructor & Destructor Documentation

SchedulerCommutator()

SchedulerCommutator ( )

default

Member Typedef Documentation

ThreadID

using ThreadID = std::thread::id

private

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

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 126 of file scheduler-commutator.hpp.

References SchedulerCommutator::groomingToken_.

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

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 142 of file scheduler-commutator.hpp.

References SchedulerCommutator::groomingToken_.

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

Here is the caller graph for this function:

holdsGroomingToken()

bool holdsGroomingToken ( ThreadID  id )

inlinenoexcept

check if the indicated thread currently holds the right to conduct internal state transitions.

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

References SchedulerCommutator::groomingToken_.

Referenced by SchedulerCommutator::ScopedGroomingGuard::~ScopedGroomingGuard(), SchedulerCommutator_test::___ensureGroomingTokenReleased(), SchedulerCommutator_test::blockGroomingToken(), SchedulerCommutator::ensureDroppedGroomingToken(), SchedulerCommutator::ScopedGroomingGuard::ensureHoldsToken(), SchedulerCommutator::findWork(), SchedulerCommutator_test::integratedWorkCycle(), SchedulerCommutator::maintainQueueHead(), SchedulerCommutator::maybeFeed(), SchedulerCommutator::postChain(), SchedulerCommutator::scatteredDelay(), SchedulerCommutator_test::verify_dispatch(), and SchedulerCommutator_test::verify_postChain().

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 462 of file scheduler-commutator.hpp.

Referenced by Scheduler::handleDutyCycle(), and Scheduler::seedCalcStream().

Here is the caller graph for this function:

maybeFeed()

void maybeFeed ( SchedulerInvocation &  layer1 )

inline

tend to the input queue if possible

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

References SchedulerCommutator::acquireGoomingToken(), SchedulerInvocation::feedPrioritisation(), SchedulerInvocation::hasPendingInput(), and SchedulerCommutator::holdsGroomingToken().

Referenced by SchedulerCommutator::dispatchCapacity().

Here is the call graph for this function:

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 182 of file scheduler-commutator.hpp.

References SchedulerInvocation::feedPrioritisation(), SchedulerCommutator::holdsGroomingToken(), SchedulerInvocation::isOutdated(), SchedulerInvocation::isOutOfTime(), and SchedulerInvocation::pullHead().

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 197 of file scheduler-commutator.hpp.

References SchedulerCommutator::acquireGoomingToken(), SchedulerInvocation::feedPrioritisation(), SchedulerCommutator::holdsGroomingToken(), SchedulerInvocation::isDue(), SchedulerInvocation::isOutdated(), SchedulerInvocation::isOutOfTime(), SchedulerCommutator::maintainQueueHead(), and SchedulerInvocation::pullHead().

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 231 of file scheduler-commutator.hpp.

References SchedulerInvocation::feedPrioritisation(), SchedulerCommutator::holdsGroomingToken(), SchedulerInvocation::instruct(), and vault::gear::activity::PASS.

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

Here is the call graph for this function:

Here is the caller graph for this function:

dispatchCapacity()

template<class DISPATCH , class CLOCK >

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 318 of file scheduler-commutator.hpp.

References SchedulerCommutator::ensureDroppedGroomingToken(), SchedulerCommutator::findWork(), SchedulerInvocation::headTime(), vault::gear::activity::KICK, LoadController::markIncomingCapacity(), LoadController::markOutgoingCapacity(), SchedulerCommutator::maybeFeed(), vault::gear::activity::PASS, SchedulerCommutator::WorkerInstruction::performStep(), and SchedulerCommutator::scatteredDelay().

Referenced by Scheduler::doWork(), 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 375 of file scheduler-commutator.hpp.

References SchedulerCommutator::acquireGoomingToken(), LoadController::DISPATCH, SchedulerCommutator::ensureDroppedGroomingToken(), SchedulerCommutator::holdsGroomingToken(), LoadController::IDLEWAIT, vault::gear::activity::PASS, LoadController::scatteredDelayTime(), vault::gear::activity::SKIP, LoadController::SPINTIME, LoadController::tendedNext(), LoadController::tendNext(), LoadController::TENDNEXT, and vault::gear::activity::WAIT.

Referenced by SchedulerCommutator::dispatchCapacity().

Here is the call graph for this function:

Here is the caller graph for this function:

ensureDroppedGroomingToken()

void ensureDroppedGroomingToken ( )

inlineprivate

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

References SchedulerCommutator::dropGroomingToken(), and SchedulerCommutator::holdsGroomingToken().

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

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

groomingToken_

atomic<ThreadID> groomingToken_ {}

private

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

Referenced by SchedulerCommutator::acquireGoomingToken(), SchedulerCommutator::dropGroomingToken(), and SchedulerCommutator::holdsGroomingToken().

Inheritance diagram for SchedulerCommutator:

Collaboration diagram for SchedulerCommutator:

---

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

• scheduler-commutator.hpp