Scheduler Class Reference

#include "vault/gear/scheduler.hpp"

Description

»Scheduler-Service« : coordinate render activities.

Todo:

WIP 11/2023

See also

BlockFlow

SchedulerUsage_test

Definition at line 222 of file scheduler.hpp.

Public Member Functions
	Scheduler (BlockFlowAlloc &activityAllocator, EngineObserver &engineObserver)
void	continueMetaJob (Time nextStart, Job planningJob, ManifestationID manID=ManifestationID())
	Place a follow-up job-planning job into the timeline.
ScheduleSpec	defineSchedule (Job job)
	Render Job builder: start definition of a schedule to invoke the given Job. More...
activity::Proc	doWork ()
	The worker-Functor: called by the active Workers from the WorkForce to pull / perform the actual render Activities.
bool	empty () const
double	getLoadIndicator ()
void	ignite ()
	Spark the engine self-regulation cycle and power up WorkForce. More...
void	seedCalcStream (Job planningJob, ManifestationID manID=ManifestationID(), FrameRate expectedAdditionalLoad=FrameRate(25))
	Set the Scheduler to work on a new CalcStream. More...
void	terminateProcessing ()
	Bring down processing destructively as fast as possible. More...

Classes
class	ExecutionCtx
struct	Setup
	Binding of worker callbacks to the scheduler implementation. More...

Friends
class	ExecutionCtx
class	ScheduleSpec
	the Job builder is allowed to allocate and dispatch
class	test::SchedulerService_test
	open private backdoor for tests

Private Member Functions
LoadController::Wiring	connectMonitoring ()
Time	getSchedTime ()
	access high-resolution-clock, rounded to µ-Ticks
void	handleDutyCycle (Time now, bool=false)
	»Tick-hook« : code to maintain sane running status. More...
void	handleWorkerTermination (bool isFailure)
	Callback invoked whenever a worker-thread is about to exit. More...
void	maybeScaleWorkForce (Time startHorizon)
	Hook invoked whenever a new task is passed in. More...
void	postChain (ActivationEvent)
	Enqueue for time-bound execution, possibly dispatch immediately. More...
void	sanityCheck (ActivationEvent const &)
void	triggerEmergency ()
	Trip the emergency brake and unwind processing while retaining all state. More...
Private Member Functions inherited from NonCopyable
	NonCopyable (NonCopyable const &)=delete
NonCopyable &	operator= (NonCopyable const &)=delete

Private Attributes
ActivityLang	activityLang_
EngineObserver &	engineObserver_
SchedulerInvocation	layer1_
SchedulerCommutator	layer2_
LoadController	loadControl_
WorkForce< Setup >	workForce_

Member Function Documentation

ignite()

void ignite ( )

inline

Spark the engine self-regulation cycle and power up WorkForce.

Note

set off automatically when put to use; while active, the duty-cycle retains itself, albeit bound to disengage when falling empty.

Definition at line 268 of file scheduler.hpp.

terminateProcessing()

void terminateProcessing ( )

inline

Bring down processing destructively as fast as possible.

Dismiss worker threads as soon as possible, and clear the queues.

Warning

Actually running Activities can not be aborted, but anything not yet scheduled will be discarded, irrespective of dependencies.

Remarks

should never need to call this in regular operation, since an empty scheduler disengages automatically.

Definition at line 287 of file scheduler.hpp.

getLoadIndicator()

double getLoadIndicator ( )

inline

Returns

a synthetic indicator fused from several observations

• 1.0 defines full work capacity yet no significant congestion
• values > 2.0 indicate overload

Definition at line 301 of file scheduler.hpp.

References LoadController::effectiveLoad().

Here is the call graph for this function:

seedCalcStream()

void seedCalcStream ( Job  planningJob, ManifestationID  manID = ManifestationID(), FrameRate  expectedAdditionalLoad = FrameRate(25)  )

inline

Set the Scheduler to work on a new CalcStream.

Parameters

planningJob	a »meta-Job« to schedule a chunk of render-Jobs.
manID	(optional) a manifestation-ID to be enabled for processing

Note

the planningJob will be dispatched immediately now, which typically will cause its dispatch in the current thread (but that is not guaranteed). The deadline is also set automatically to a very large leeway (1/10 sec), and the new planning job is marked as compulsory — implying that the Scheduler will trigger emergency if this deadline can not be met. Emergency will cause all PlayProcess to be paused.

Remarks

it is up to the planning instance to use this mechanism properly; the idea is to place follow-up jobs repeatedly, always to define the next chunk of work jobs. If a ManifestationID is given, then obviously the work jobs must use the same ID, since jobs with an ID not explicitly enabled will be silently discarded (unless the ID is zero, which is always implicitly enabled). Moreover, the recommendation is to start planning with at least 20ms of remaining headroom, to ensure smooth allocation of capacity.

Definition at line 327 of file scheduler.hpp.

References SchedulerInvocation::activate(), ActivityLang::announceLoad(), and SchedulerCommutator::requireGroomingTokenHere().

Referenced by TestChainLoad< maxFan >::ScheduleCtx::continuation().

Here is the call graph for this function:

Here is the caller graph for this function:

defineSchedule()

ScheduleSpec defineSchedule ( Job  job )

inline

Render Job builder: start definition of a schedule to invoke the given Job.

Use the functions on the returned builder to fill in the details of the schedule; defining a start point and a deadline is mandatory. Issue this schedule then by invoking post()

Warning

the deadline is also used to manage the allocation.

Definition at line 366 of file scheduler.hpp.

Referenced by TestChainLoad< maxFan >::ScheduleCtx::continuation(), and TestChainLoad< maxFan >::ScheduleCtx::disposeStep().

Here is the caller graph for this function:

postChain()

void postChain ( ActivationEvent  actEvent )

inlineprivate

Enqueue for time-bound execution, possibly dispatch immediately.

This is the »main entrance« to get some Activity scheduled.

Parameters

actEvent

the Activity, start time and deadline and optionally further context information

Definition at line 617 of file scheduler.hpp.

References SchedulerCommutator::postChain().

Here is the call graph for this function:

handleDutyCycle()

void handleDutyCycle ( Time  now, bool  forceContinuation = false  )

inlineprivate

»Tick-hook« : code to maintain sane running status.

This function will be invoked regularly while the scheduler is actively processing; in fact this function determines when the scheduler falls empty and can be shut down — and thus regular invocation is equivalent to running state. Code for all kinds of status updates, low-level clean-up and maintenance work related to the building blocks of the scheduler shall be added here. It will be invoked from within some (random) worker thread, frequently enough for humans to seem like an immediate response, but with sufficient large time period to amortise even slightly more computational expensive work; IO and possibly blocking operations should be avoided here though. Exceptions emanating from here will shut down the engine.

Parameters

forceContinuation

whether a follow-up DutyCycle must happen, irrespective if the queue has still further entries. Used on first Tick-Cycle directly after ignition, which is then also shortened (to improve scheduling precision)

Definition at line 644 of file scheduler.hpp.

References ActivityLang::createTick(), ActivityLang::discardBefore(), vault::gear::anonymous_namespace{scheduler.hpp}::DUTY_CYCLE_PERIOD, vault::gear::anonymous_namespace{scheduler.hpp}::DUTY_CYCLE_TOLERANCE, SchedulerInvocation::feedPrioritisation(), SchedulerInvocation::isOutdated(), SchedulerInvocation::isOutOfTime(), SchedulerCommutator::postChain(), SchedulerInvocation::pullHead(), SchedulerCommutator::requireGroomingTokenHere(), LoadController::updateState(), and vault::gear::anonymous_namespace{load-controller.hpp}::WORK_HORIZON.

Referenced by Scheduler::ExecutionCtx::tick().

Here is the call graph for this function:

Here is the caller graph for this function:

handleWorkerTermination()

void handleWorkerTermination ( bool  isFailure )

inlineprivate

Callback invoked whenever a worker-thread is about to exit.

Parameters

isFailuere

if the exit was caused by uncaught exception

Definition at line 680 of file scheduler.hpp.

References LoadController::markWorkerExit().

Here is the call graph for this function:

maybeScaleWorkForce()

void maybeScaleWorkForce ( Time  startHorizon )

inlineprivate

Hook invoked whenever a new task is passed in.

Ensures that the Scheduler is in running state and possibly steps up the WorkForce if not yet running at full computation power.

Note

the capacity scales down automatically when some workers fall idle for extended time (> 2sec).

Definition at line 697 of file scheduler.hpp.

References LoadController::ensureCapacity().

Here is the call graph for this function:

triggerEmergency()

void triggerEmergency ( )

inlineprivate

Trip the emergency brake and unwind processing while retaining all state.

Todo:

as of 4/2024 it is not clear what Scheduler-Emergency actually entails; thus it can not be determined at which level of the component the handler must reside, and how it can be reached. Notably there exists a situation in SchedulerCommutatior::findWork(), where emergency can happen, yet in its current configuration, the Layer-2 has no access to the top-level Scheduler component. /////////////////////////////////////////////////TICKET #1362 : where to handle Scheduler-Emergency

Definition at line 715 of file scheduler.hpp.

connectMonitoring()

LoadController::Wiring connectMonitoring ( )

inlineprivate

connect state signals for use by the LoadController

Definition at line 392 of file scheduler.hpp.

References Config::COMPUTATION_CAPACITY, and vault::gear::test::anonymous_namespace{work-force-test.cpp}::setup().

Here is the call graph for this function:

Inheritance diagram for Scheduler:

Collaboration diagram for Scheduler:

---

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

• scheduler.hpp