#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.

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. More...

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 a 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 259 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 278 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 292 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 318 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 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(), and ActivityLang::dispatchChain().

Here is the call 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 SchedulerCommutator::postChain().

Here is the call 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 ActivityLang::createTick(), ActivityLang::discardBefore(), vault::gear::anonymous_namespace{scheduler.hpp}::DUTY_CYCLE_PERIOD, vault::gear::anonymous_namespace{scheduler.hpp}::DUTY_CYCLE_TOLERANCE, SchedulerCommutator::maintainQueueHead(), SchedulerCommutator::postChain(), 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 678 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 695 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 713 of file scheduler.hpp.

◆ connectMonitoring()

LoadController::Wiring connectMonitoring ( )

inlineprivate

connect state signals for use by the LoadController

Definition at line 383 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

Description

Public Member Functions

Classes

Friends

Private Member Functions

Private Attributes

Member Function Documentation

◆ ignite()

◆ terminateProcessing()

◆ getLoadIndicator()

◆ seedCalcStream()

◆ defineSchedule()

◆ doWork()

◆ postChain()

◆ handleDutyCycle()

◆ handleWorkerTermination()

◆ maybeScaleWorkForce()

◆ triggerEmergency()

◆ connectMonitoring()