#include "vault/gear/scheduler.hpp"

Description

»Scheduler-Service« : coordinate render activities.

WIP 11/2023

largely completed spring 2024
passes stress testing with good performance
TODO further integration will require to extract a Scheduler-Interface

See also: BlockFlow; SchedulerUsage_test

Definition at line 213 of file scheduler.hpp.

Classes
class	ExecutionCtx

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

Public Member Functions
	Scheduler (BlockFlowAlloc &activityAllocator, EngineObserver &engineObserver)

bool	empty () const

void	ignite ()
	Spark the engine self-regulation cycle and power up WorkForce.

void	terminateProcessing ()
	Bring down processing destructively as fast as possible.

double	getLoadIndicator ()

void	seedCalcStream (Job planningJob, ManifestationID manID=ManifestationID(), FrameRate expectedAdditionalLoad=FrameRate(25))
	Set the Scheduler to work on a new CalcStream.

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.

activity::Proc	doWork ()
	The worker-Functor: called by the active Workers from the WorkForce to pull / perform the actual render Activities.

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
void	postChain (ActivationEvent)
	Enqueue for time-bound execution, possibly dispatch immediately.

void	sanityCheck (ActivationEvent const &)

void	handleDutyCycle (Time now, bool=false)
	»Tick-hook« : code to maintain a sane running status.

void	handleWorkerTermination (bool isFailure)
	Callback invoked whenever a worker-thread is about to exit.

void	maybeScaleWorkForce (Time startHorizon)
	Hook invoked whenever a new task is passed in.

void	triggerEmergency ()
	Trip the emergency brake and unwind processing while retaining all state.

LoadController::Wiring	connectMonitoring ()

Time	getSchedTime ()
	access high-resolution-clock, rounded to µ-Ticks

Private Member Functions inherited from NonCopyable
	~NonCopyable ()=default

	NonCopyable ()=default

	NonCopyable (NonCopyable const &)=delete

NonCopyable &	operator= (NonCopyable const &)=delete

Private Attributes
SchedulerInvocation	layer1_

SchedulerCommutator	layer2_

WorkForce< Setup >	workForce_

ActivityLang	activityLang_

LoadController	loadControl_

EngineObserver &	engineObserver_

Constructor & Destructor Documentation

◆ Scheduler()

Scheduler	(	BlockFlowAlloc &	activityAllocator,
		EngineObserver &	engineObserver
	)

inline

Definition at line 235 of file scheduler.hpp.

Member Function Documentation

◆ empty()

bool empty ( ) const

inline

Definition at line 247 of file scheduler.hpp.

References SchedulerInvocation::empty(), and Scheduler::layer1_.

Referenced by Scheduler::handleDutyCycle(), Scheduler::ignite(), and Scheduler::maybeScaleWorkForce().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ 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 259 of file scheduler.hpp.

References Scheduler::empty(), Scheduler::handleDutyCycle(), RealClock::now(), and Scheduler::workForce_.

Referenced by Scheduler::maybeScaleWorkForce().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ 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 278 of file scheduler.hpp.

References SchedulerInvocation::discardSchedule(), Scheduler::layer1_, and Scheduler::workForce_.

Here is the call graph for this function:

◆ 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 292 of file scheduler.hpp.

References LoadController::effectiveLoad(), and Scheduler::loadControl_.

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

References SchedulerInvocation::activate(), Scheduler::activityLang_, ActivityLang::announceLoad(), Scheduler::continueMetaJob(), Scheduler::layer1_, Scheduler::layer2_, RealClock::now(), and SchedulerCommutator::requireGroomingTokenHere().

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

Here is the call graph for this function:

Here is the caller graph for this function:

◆ continueMetaJob()

void continueMetaJob	(	Time	nextStart,
		Job	planningJob,
		ManifestationID	manID = `ManifestationID()`
	)

inline

Place a follow-up job-planning job into the timeline.

Definition at line 333 of file scheduler.hpp.

References Scheduler::activityLang_, ActivityLang::buildMetaJob(), and Scheduler::postChain().

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

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

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

Here is the caller graph for this function:

◆ doWork()

activity::Proc doWork ( )

inline

The worker-Functor: called by the active Workers from the WorkForce to pull / perform the actual render Activities.

Remarks

this is the »internal service entrance point« for render workers and is implemented by combining all parts of the Scheduler

the processing environment of the ActivityLang
Layer-1 for queue management
Layer-2 for execution
the LoadController

Definition at line 520 of file scheduler.hpp.

References SchedulerCommutator::dispatchCapacity(), ActivityLang::dispatchChain(), Scheduler::getSchedTime(), Scheduler::layer1_, Scheduler::layer2_, and Scheduler::loadControl_.

Referenced by Scheduler::Setup::doWork().

Here is the call graph for this function:

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

References Scheduler::layer1_, Scheduler::layer2_, Scheduler::maybeScaleWorkForce(), SchedulerCommutator::postChain(), Scheduler::sanityCheck(), and ActivationEvent::startTime().

Referenced by Scheduler::continueMetaJob(), and ScheduleSpec::post().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ sanityCheck()

void sanityCheck ( ActivationEvent const & event )

inlineprivate

Definition at line 593 of file scheduler.hpp.

References Time::ANYTIME, ActivationEvent::deathTime(), Scheduler::getSchedTime(), Time::NEVER, and ActivationEvent::startTime().

Referenced by Scheduler::ExecutionCtx::post(), and Scheduler::postChain().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ handleDutyCycle()

void handleDutyCycle	(	Time	now,
		bool	forceContinuation = `false`
	)

inlineprivate

»Tick-hook« : code to maintain a 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 647 of file scheduler.hpp.

References Scheduler::activityLang_, ActivityLang::createTick(), ActivityLang::discardBefore(), Scheduler::empty(), Scheduler::layer1_, Scheduler::layer2_, Scheduler::loadControl_, SchedulerCommutator::maintainQueueHead(), SchedulerCommutator::postChain(), SchedulerCommutator::requireGroomingTokenHere(), Scheduler::triggerEmergency(), and LoadController::updateState().

Referenced by Scheduler::ignite(), and 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 678 of file scheduler.hpp.

References Scheduler::loadControl_, LoadController::markWorkerExit(), and Scheduler::triggerEmergency().

Referenced by Scheduler::Setup::finalHook().

Here is the call graph for this function:

Here is the caller 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 695 of file scheduler.hpp.

References Scheduler::empty(), LoadController::ensureCapacity(), Scheduler::ignite(), and Scheduler::loadControl_.

Referenced by Scheduler::postChain().

Here is the call graph for this function:

Here is the caller 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 713 of file scheduler.hpp.

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

Here is the caller graph for this function: