#include "vault/gear/load-controller.hpp"

Description

Controller to coordinate resource usage related to the Scheduler.

implements the schematics for capacity redistribution
provides some performance indicators, notably the LoadController::effectiveLoad()
Todo:
WIP-WIP 10/2023 gradually filling in functionality as needed

See also
BlockFlow

Scheduler

Definition at line 144 of file load-controller.hpp.

Classes
struct	Wiring

Public Types
enum	Capacity { DISPATCH , TENDNEXT , SPINTIME , NEARTIME , WORKTIME , IDLEWAIT }
	Allocation of capacity to time horizon of expected work. More...

Static Public Member Functions
static Capacity	classifyTimeHorizon (Offset off)
	classification of time horizon for scheduling

Public Member Functions
	LoadController (Wiring &&wiring)

	LoadController ()

int64_t	averageLag () const

int64_t	setCurrentAverageLag (int64_t lag)

double	effectiveLoad () const

void	updateState (Time)
	periodic call to build integrated state indicators

void	markWorkerExit ()
	statistics update on scaling down the WorkForce

void	ensureCapacity (Time startHorizon)
	Hook to check and possibly scale up WorkForce to handle one additional job.

bool	tendedNext (Time nextHead) const
	did we already tend for the indicated next relevant head time?

void	tendNext (Time nextHead)
	Mark the indicated next head time as tended.

Capacity	markOutgoingCapacity (Time head, Time now)
	decide how this thread's capacity shall be used after it returned from being actively employed

Capacity	markIncomingCapacity (Time head, Time now)
	decide how this thread's capacity shall be used when returning from idle wait and asking for work

Offset	scatteredDelayTime (Time now, Capacity capacity)
	Generate a time offset to relocate currently unused capacity to a time range where it's likely to be needed.

Private Member Functions
void	markLagSample (Time head, Time now)

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

	NonCopyable ()=default

	NonCopyable (NonCopyable const &)=delete

NonCopyable &	operator= (NonCopyable const &)=delete

Private Attributes
const Wiring	wiring_

TimeVar	tendedHead_ {Time::ANYTIME}

atomic_int64_t	sampledLag_ {0}

Constructor & Destructor Documentation

◆ LoadController() [1/2]

LoadController ( Wiring && wiring )

inlineexplicit

Definition at line 157 of file load-controller.hpp.

◆ LoadController() [2/2]

LoadController ( )

inline

Definition at line 161 of file load-controller.hpp.

Class Documentation

◆ vault::gear::LoadController::Wiring

struct vault::gear::LoadController::Wiring

Class Members
function< size_t()>	maxCapacity {[]{ return 1; }}
function< size_t()>	currWorkForceSize {[]{ return 0; }}
function< void(uint)>	stepUpWorkForce {[](uint){}}

Collaboration diagram for LoadController::Wiring:

Member Enumeration Documentation

◆ Capacity

enum Capacity

Allocation of capacity to time horizon of expected work.

Enumerator
DISPATCH	sent to work
TENDNEXT	reserved for next task
SPINTIME	awaiting imminent activities
NEARTIME	capacity for active processing required
WORKTIME	typical stable work task rhythm expected
IDLEWAIT	time to go to sleep

Definition at line 300 of file load-controller.hpp.

Member Function Documentation

◆ markLagSample()

void markLagSample	(	Time	head,
		Time	now
	)

inlineprivate

evaluate the situation encountered when a worker calls for work.

Remarks: this function updates an exponential moving average of schedule head distance in a concurrency safe way. The value sampled is clamped to prevent poisoning by excess peaks.

Warning: Called from a hot path, with the potential to create congestion. Measurements indicate single call < 200ns and < 5µs when contended.

Definition at line 182 of file load-controller.hpp.

References TimeValue::isRegular(), LoadController::Wiring::maxCapacity, LoadController::sampledLag_, and LoadController::wiring_.

Referenced by LoadController::markIncomingCapacity().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ averageLag()

int64_t averageLag ( ) const

inline

Returns: guess of current scheduler pressure

Remarks: the value is sampled at the points where workers pull work. Since these »capacity events« happen randomly, the current distance to the schedule head hints at either free headroom or overload leading to congestion.

See also: markLagSample

Definition at line 204 of file load-controller.hpp.

References LoadController::sampledLag_.

Referenced by LoadController::effectiveLoad(), LoadController::ensureCapacity(), and LoadController::updateState().

Here is the caller graph for this function:

◆ setCurrentAverageLag()

int64_t setCurrentAverageLag ( int64_t lag )

inline

(re)set the currently seen average lag.

Returns: the previous average value

Remarks: intended for unit testing and state reset; thread-save. Regular use not recommended.

Definition at line 216 of file load-controller.hpp.

References LoadController::sampledLag_.

◆ effectiveLoad()

double effectiveLoad ( ) const

inline

Returns: guess of current load relative to full load

Remarks

based on the fusion of several state values, which can be retrieved with low overhead

the used fraction of possible concurrency
sampling of distance to next task

Definition at line 229 of file load-controller.hpp.

References LoadController::averageLag(), LoadController::Wiring::currWorkForceSize, LoadController::Wiring::maxCapacity, and LoadController::wiring_.

Referenced by Scheduler::getLoadIndicator().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ updateState()

void updateState ( Time )

inline

periodic call to build integrated state indicators

Definition at line 242 of file load-controller.hpp.

References LoadController::averageLag(), LoadController::Wiring::stepUpWorkForce, and LoadController::wiring_.

Referenced by Scheduler::handleDutyCycle().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ markWorkerExit()

void markWorkerExit ( )

inline

statistics update on scaling down the WorkForce

Definition at line 256 of file load-controller.hpp.

Referenced by Scheduler::handleWorkerTermination().

Here is the caller graph for this function:

◆ ensureCapacity()

void ensureCapacity ( Time startHorizon )

inline

Hook to check and possibly scale up WorkForce to handle one additional job.

Definition at line 265 of file load-controller.hpp.

References LoadController::averageLag(), LoadController::Wiring::stepUpWorkForce, and LoadController::wiring_.

Referenced by Scheduler::maybeScaleWorkForce().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ tendedNext()

bool tendedNext ( Time nextHead ) const

inline

did we already tend for the indicated next relevant head time?

Note: const and non-grooming

Definition at line 278 of file load-controller.hpp.

References TimeValue::isRegular(), and LoadController::tendedHead_.

Referenced by LoadController::markOutgoingCapacity(), SchedulerCommutator::scatteredDelay(), and SchedulerLoadControl_test::tendNextActivity().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ tendNext()

void tendNext ( Time nextHead )

inline

Mark the indicated next head time as tended.

Remarks: while this is just implemented as simple state, the meaning is that some free capacity has been directed towards that time, and thus further capacity go elsewhere.

Warning: must hold the grooming-Token to use this mutation.

Definition at line 292 of file load-controller.hpp.

References LoadController::tendedHead_.

Referenced by SchedulerLoadControl_test::classifyCapacity(), SchedulerCommutator::scatteredDelay(), SchedulerLoadControl_test::scatteredReCheck(), and SchedulerLoadControl_test::tendNextActivity().

Here is the caller graph for this function:

◆ classifyTimeHorizon()

static Capacity classifyTimeHorizon ( Offset off )

inlinestatic

classification of time horizon for scheduling

Definition at line 310 of file load-controller.hpp.

References LoadController::DISPATCH, LoadController::IDLEWAIT, LoadController::NEARTIME, LoadController::SPINTIME, LoadController::WORKTIME, and Time::ZERO.

Referenced by SchedulerLoadControl_test::classifyHorizon(), LoadController::markIncomingCapacity(), and LoadController::markOutgoingCapacity().

Here is the caller graph for this function:

◆ markOutgoingCapacity()

Capacity markOutgoingCapacity	(	Time	head,
		Time	now
	)

inline

decide how this thread's capacity shall be used after it returned from being actively employed

Definition at line 323 of file load-controller.hpp.

References LoadController::classifyTimeHorizon(), LoadController::IDLEWAIT, LoadController::SPINTIME, LoadController::tendedNext(), LoadController::TENDNEXT, and LoadController::WORKTIME.

Referenced by SchedulerLoadControl_test::classifyCapacity(), SchedulerCommutator::dispatchCapacity(), and LoadController::markIncomingCapacity().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ markIncomingCapacity()

Capacity markIncomingCapacity	(	Time	head,
		Time	now
	)

inline

decide how this thread's capacity shall be used when returning from idle wait and asking for work

Definition at line 335 of file load-controller.hpp.

References LoadController::classifyTimeHorizon(), LoadController::IDLEWAIT, LoadController::markLagSample(), LoadController::markOutgoingCapacity(), and LoadController::NEARTIME.

Referenced by SchedulerLoadControl_test::classifyCapacity(), and SchedulerCommutator::dispatchCapacity().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ scatteredDelayTime()

Offset scatteredDelayTime	(	Time	now,
		Capacity	capacity
	)

inline

Generate a time offset to relocate currently unused capacity to a time range where it's likely to be needed.

Assuming the classification is based on the current distance to the next Activity known to the scheduler (the next tended head time).

for capacity immediately to be dispatched this function will not be used, yet returns logically sound values.
after the next head time has been tended for, free capacity should be relocated into a time span behind that point
the closer the next head time, the more focused this relocation
but each individual delay is randomised within those time bounds, to produce an even »flow« of capacity on average. Randomisation relies on a hash (bit rotation) of current time, broken down to the desired time horizon.

Definition at line 361 of file load-controller.hpp.

References LoadController::DISPATCH, vault::gear::hash_value(), LoadController::IDLEWAIT, LoadController::NEARTIME, LoadController::SPINTIME, LoadController::tendedHead_, LoadController::TENDNEXT, LoadController::WORKTIME, Time::ZERO, and Offset::ZERO.

Referenced by SchedulerCommutator::scatteredDelay(), and SchedulerLoadControl_test::scatteredReCheck().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ wiring_

const Wiring wiring_

private

Definition at line 166 of file load-controller.hpp.

Referenced by LoadController::effectiveLoad(), LoadController::ensureCapacity(), LoadController::markLagSample(), and LoadController::updateState().

◆ tendedHead_

TimeVar tendedHead_ {Time::ANYTIME}

private

Definition at line 168 of file load-controller.hpp.

Referenced by LoadController::scatteredDelayTime(), LoadController::tendedNext(), and LoadController::tendNext().

◆ sampledLag_

atomic_int64_t sampledLag_ {0}

private

Definition at line 171 of file load-controller.hpp.

Referenced by LoadController::averageLag(), LoadController::markLagSample(), and LoadController::setCurrentAverageLag().

Inheritance diagram for LoadController:

Collaboration diagram for LoadController:

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

load-controller.hpp

Description

Classes

Public Types

Static Public Member Functions

Public Member Functions

Private Member Functions

Private Attributes

Constructor & Destructor Documentation

◆ LoadController() [1/2]

◆ LoadController() [2/2]

Class Documentation

◆ vault::gear::LoadController::Wiring

Member Enumeration Documentation

◆ Capacity

Member Function Documentation

◆ markLagSample()

◆ averageLag()

◆ setCurrentAverageLag()

◆ effectiveLoad()

◆ updateState()

◆ markWorkerExit()

◆ ensureCapacity()

◆ tendedNext()

◆ tendNext()

◆ classifyTimeHorizon()

◆ markOutgoingCapacity()

◆ markIncomingCapacity()

◆ scatteredDelayTime()

Member Data Documentation

◆ wiring_

◆ tendedHead_

◆ sampledLag_