LoadController Class Reference

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

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

Public Member Functions
	LoadController (Wiring &&wiring)
int64_t	averageLag () const
double	effectiveLoad () const
void	ensureCapacity (Time startHorizon)
	Hook to check and possibly scale up WorkForce to handle one additional job.
Capacity	markIncomingCapacity (Time head, Time now)
	decide how this thread's capacity shall be used when returning from idle wait and asking for work
Capacity	markOutgoingCapacity (Time head, Time now)
	decide how this thread's capacity shall be used after it returned from being actively employed
void	markWorkerExit ()
	statistics update on scaling down the WorkForce
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. More...
int64_t	setCurrentAverageLag (int64_t lag)
bool	tendedNext (Time nextHead) const
	did we already tend for the indicated next relevant head time? More...
void	tendNext (Time nextHead)
	Mark the indicated next head time as tended. More...
void	updateState (Time)
	periodic call to build integrated state indicators

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

Classes
struct	Wiring

Private Member Functions
void	markLagSample (Time head, Time now)
Private Member Functions inherited from NonCopyable
	NonCopyable (NonCopyable const &)=delete
NonCopyable &	operator= (NonCopyable const &)=delete

Private Attributes
atomic_int64_t	sampledLag_ {0}
TimeVar	tendedHead_ {Time::ANYTIME}
const Wiring	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.

---

Class Documentation

vault::gear::LoadController::Wiring

struct vault::gear::LoadController::Wiring

Class Members
function< size_t()>	maxCapacity
function< size_t()>	currWorkForceSize
function< void(uint)>	stepUpWorkForce

Collaboration diagram for LoadController::Wiring:

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(), vault::gear::anonymous_namespace{load-controller.hpp}::LAG_SAMPLE_DAMPING, vault::gear::anonymous_namespace{load-controller.hpp}::SLEEP_HORIZON, and vault::gear::anonymous_namespace{load-controller.hpp}::WORK_HORIZON.

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.

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.

Referenced by SchedulerLoadControl_test::indicateAverageLoad().

Here is the caller graph for this function:

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(), vault::gear::anonymous_namespace{load-controller.hpp}::STANDARD_LAG, and vault::gear::anonymous_namespace{load-controller.hpp}::WORK_HORIZON.

Referenced by Scheduler::getLoadIndicator().

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().

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.

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

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.

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

Here is the caller graph for this function:

Inheritance diagram for LoadController:

Collaboration diagram for LoadController:

---

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

• load-controller.hpp