#include "vault/gear/block-flow.hpp"

Description

template<class CONF = blockFlow::DefaultConfig>
class vault::gear::BlockFlow< CONF >

Allocation scheme for the Scheduler, based on Epoch(s).

Scheduling entails to provide a chain of Activity definitions, which will then »flow« through the priority queue until invocation.

See also: ActivityLang; SchedulerCommutator; BlockFlow_test

Definition at line 341 of file block-flow.hpp.

Public Types
using	Allocator = mem::ExtentFamily< Activity, EPOCH_SIZ >

using	Epoch = blockFlow::Epoch< Allocator >

using	EpochIter = lib::IterableDecorator< StorageAdaptor >
	Adapted storage-Extent iterator, directly exposing Epoch&.

using	Extent = typename Allocator::Extent

using	RawIter = typename Allocator::iterator

using	Strategy = blockFlow::Strategy< CONF >

Public Member Functions
void	adjustEpochStep (double factor)

void	announceAdditionalFlow (FrameRate additionalFps)
	provide a hint to the self-regulating allocation scheme. More...

void	discardBefore (Time deadline)
	Clean-up all storage related to activities before the given deadline. More...

Duration	getEpochStep () const

void	markEpochOverflow ()
	Notify and adjust Epoch capacity as consequence of exhausting an Epoch. More...

void	markEpochUnderflow (TimeVar actualLen, double fillFactor)
	On clean-up of past Epochs, the actual fill factor is checked to guess an Epoch duration to make optimal use of epoch storage. More...

AllocatorHandle	until (Time deadline)
	initiate allocations for activities to happen until some deadline More...

Public Member Functions inherited from Strategy< CONF >
size_t	averageEpochs () const

double	boostFactor () const

double	boostFactorOverflow () const
	< reduced logarithmically, since overflow is detected on individual allocations

CONF const &	config () const

size_t	framesPerEpoch () const

size_t	initialEpochCnt () const
	< reserve allocation headroom for two duty cycles

Duration	initialEpochStep () const

size_t	initialFrameRate () const

Duration	timeStep_cutOff () const
	< prevent stalling Epoch progression when reaching saturation

Public Attributes
double	_cache_boostFactorOverflow = Strategy::boostFactorOverflow()

Duration	_cache_timeStep_cutOff = Strategy::timeStep_cutOff()

Classes
class	AllocatorHandle
	Local handle to allow allocating a collection of Activities, all sharing a common deadline. More...

class	StorageAdaptor
	Adapt the access to the raw storage to present the Extents as Epoch; also caches the address resolution for performance reasons (+20%). More...

Friends
class	FlowDiagnostic< CONF >
	„backdoor“ to watch internals from tests

Private Member Functions
void	___sanityCheckAlloc (size_t newBlockCnt)

EpochIter	allEpochs ()

Epoch &	firstEpoch ()

Epoch &	lastEpoch ()

Time	updatePastDeadline (TimeVar newDeadline)

Private Member Functions inherited from NonCopyable
	NonCopyable (NonCopyable const &)=delete

NonCopyable &	operator= (NonCopyable const &)=delete

Static Private Member Functions
static Epoch &	asEpoch (Extent &extent)

Private Attributes
Allocator	alloc_

TimeVar	epochStep_

TimeVar	pastDeadline_ {Time::ANYTIME}

Static Private Attributes
static constexpr size_t	EPOCH_SIZ = CONF::EPOCH_SIZ

Member Function Documentation

◆ asEpoch()

static Epoch& asEpoch ( Extent & extent )

inlinestaticprivate

use a raw storage Extent as Epoch (unchecked cast)

Definition at line 363 of file block-flow.hpp.

◆ until()

AllocatorHandle until ( Time deadline )

inline

initiate allocations for activities to happen until some deadline

Returns: opaque handle allowing to perform several allocations.

Warning: should not be used after the deadline has passed, since memory will then be re-used and overwritten.

Definition at line 516 of file block-flow.hpp.

Referenced by ActivityLang::createTick(), BlockFlow_test::placeActivity(), ActivityLang::setupActivityScheme(), and BlockFlow_test::simpleUsage().

Here is the caller graph for this function:

◆ discardBefore()

void discardBefore ( Time deadline )

inline

Clean-up all storage related to activities before the given deadline.

Note: when some Epoch is blocked by pending IO, all subsequent Epochs will be kept alive too, since the returning IO operation may trigger activities there (at least up to the point where the control logic detects a timeout and abandons the execution chain).

Definition at line 574 of file block-flow.hpp.

Referenced by ActivityLang::discardBefore(), and BlockFlow_test::simpleUsage().

Here is the caller graph for this function:

◆ markEpochOverflow()

void markEpochOverflow ( )

inline

Notify and adjust Epoch capacity as consequence of exhausting an Epoch.

Whenever some Epoch can not accommodate a required allocation, the allocation is placed into subsequent Epoch(s) and then this event is triggered, reducing the epochStep_ by #OVERFLOW_BOOST_FACTOR to increase capacity.

Definition at line 602 of file block-flow.hpp.

Referenced by BlockFlow< CONF >::AllocatorHandle::create().

Here is the caller graph for this function:

◆ markEpochUnderflow()

void markEpochUnderflow	(	TimeVar	actualLen,
		double	fillFactor
	)

inline

On clean-up of past Epochs, the actual fill factor is checked to guess an Epoch duration to make optimal use of epoch storage.

Assuming that requested Activity deadlines are evenly spaced, for a simple heuristic we can just divide actual Epoch duration by the fill factor (longer Epoch => less capacity). To avoid control oscillations however, it seems prudent to use damping by an exponential moving average, nominally over #Strategy::averageEpochs(). The current epochStep_ is assumed to be such a moving average, and will be updated accordingly.

Definition at line 622 of file block-flow.hpp.

◆ announceAdditionalFlow()

void announceAdditionalFlow ( FrameRate additionalFps )

inline

provide a hint to the self-regulating allocation scheme.

Signalling additional calculation flow in advance will immediately reduce the Epoch stepping to accommodate for more Activities per time unit, thereby preventing excessive overflow and reduced performance, until the mechanism has adapted itself to the actual situation after roughly 2sec.

Definition at line 652 of file block-flow.hpp.

Referenced by ActivityLang::announceLoad().

Here is the caller graph for this function:

◆ updatePastDeadline()

Time updatePastDeadline ( TimeVar newDeadline )

inlineprivate

helper to calculate the duration of the oldest Epoch.

Remarks: since we store the deadline for each Epoch, not it's duration, we need to memorise and update a starting point, to calculate the duration, which is used to guess an averaged optimal duration.

Parameters

current deadline of the oldest block, about to be discarded

Returns: the memorised previous oldest deadline

Definition at line 689 of file block-flow.hpp.

Inheritance diagram for BlockFlow< CONF >:

Collaboration diagram for BlockFlow< CONF >:

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

block-flow.hpp

Description

template<class CONF = blockFlow::DefaultConfig> class vault::gear::BlockFlow< CONF >

Public Types

Public Member Functions

Public Attributes

Classes

Friends

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Member Function Documentation

◆ asEpoch()

◆ until()

◆ discardBefore()

◆ markEpochOverflow()

◆ markEpochUnderflow()

◆ announceAdditionalFlow()

◆ updatePastDeadline()

template<class CONF = blockFlow::DefaultConfig>
class vault::gear::BlockFlow< CONF >