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

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

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

using	Strategy = blockFlow::Strategy< CONF >

using	RawIter = Allocator::iterator

using	Extent = Allocator::Extent

using	Epoch = blockFlow::Epoch< Allocator >

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

Public Attributes
Duration	_cache_timeStep_cutOff = Strategy::timeStep_cutOff()

double	_cache_boostFactorOverflow = Strategy::boostFactorOverflow()

Public Member Functions
	BlockFlow ()

Duration	getEpochStep () const

void	adjustEpochStep (double factor)

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

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

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

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.

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

CONF const &	config () const

Public Member Functions inherited from Strategy< CONF >
CONF const &	config () const

size_t	framesPerEpoch () const

size_t	initialFrameRate () const

Duration	initialEpochStep () const

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

size_t	averageEpochs () const

double	boostFactor () const

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

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

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

Private Member Functions
Epoch &	firstEpoch ()

Epoch &	lastEpoch ()

EpochIter	allEpochs ()

Time	updatePastDeadline (TimeVar newDeadline)

void	___sanityCheckAlloc (size_t newBlockCnt)

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

	NonCopyable ()=default

	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

Constructor & Destructor Documentation

◆ BlockFlow()

template<class CONF = blockFlow::DefaultConfig>

BlockFlow ( )

inline

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

Member Typedef Documentation

◆ Allocator

template<class CONF = blockFlow::DefaultConfig>

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

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

◆ Strategy

template<class CONF = blockFlow::DefaultConfig>

using Strategy = blockFlow::Strategy<CONF>

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

◆ RawIter

template<class CONF = blockFlow::DefaultConfig>

using RawIter = Allocator::iterator

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

◆ Extent

template<class CONF = blockFlow::DefaultConfig>

using Extent = Allocator::Extent

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

◆ Epoch

template<class CONF = blockFlow::DefaultConfig>

using Epoch = blockFlow::Epoch<Allocator>

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

◆ EpochIter

template<class CONF = blockFlow::DefaultConfig>

using EpochIter = lib::IterableDecorator<StorageAdaptor>

Adapted storage-Extent iterator, directly exposing Epoch&.

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

Member Function Documentation

◆ asEpoch()

template<class CONF = blockFlow::DefaultConfig>

static Epoch & asEpoch ( Extent & extent )

inlinestaticprivate

use a raw storage Extent as Epoch (unchecked cast)

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

Referenced by BlockFlow< CONF >::StorageAdaptor::accessEpoch(), BlockFlow< CONF >::firstEpoch(), and BlockFlow< CONF >::lastEpoch().

Here is the caller graph for this function:

◆ getEpochStep()

template<class CONF = blockFlow::DefaultConfig>

Duration getEpochStep ( ) const

inline

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

References BlockFlow< CONF >::epochStep_.

Referenced by BlockFlow_test::adjustEpochs(), BlockFlow_test::announceLoad(), BlockFlow< CONF >::AllocatorHandle::claimSlot(), BlockFlow_test::placeActivity(), BlockFlow_test::simpleUsage(), and BlockFlow_test::storageFlow().

Here is the caller graph for this function:

◆ adjustEpochStep()

template<class CONF = blockFlow::DefaultConfig>

void adjustEpochStep ( double factor )

inline

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

References BlockFlow< CONF >::epochStep_.

Referenced by BlockFlow< CONF >::markEpochOverflow(), and BlockFlow< CONF >::markEpochUnderflow().

Here is the caller graph for this function:

◆ until()

template<class CONF = blockFlow::DefaultConfig>

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.

References BlockFlow< CONF >::___sanityCheckAlloc(), BlockFlow< CONF >::alloc_, ExtentFamily< T, siz >::begin(), Epoch< ALO >::deadline(), ExtentFamily< T, siz >::end(), BlockFlow< CONF >::epochStep_, BlockFlow< CONF >::firstEpoch(), BlockFlow< CONF >::lastEpoch(), ExtentFamily< T, siz >::openNew(), and Epoch< ALO >::setup().

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

Here is the call graph for this function:

Here is the caller graph for this function:

◆ discardBefore()

template<class CONF = blockFlow::DefaultConfig>

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.

References BlockFlow< CONF >::allEpochs(), BlockFlow< CONF >::alloc_, ExtentFamily< T, siz >::dropOld(), BlockFlow< CONF >::firstEpoch(), BlockFlow< CONF >::markEpochUnderflow(), and BlockFlow< CONF >::updatePastDeadline().

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

Here is the call graph for this function:

Here is the caller graph for this function:

◆ markEpochOverflow()

template<class CONF = blockFlow::DefaultConfig>

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.

References BlockFlow< CONF >::_cache_boostFactorOverflow, BlockFlow< CONF >::_cache_timeStep_cutOff, BlockFlow< CONF >::adjustEpochStep(), and BlockFlow< CONF >::epochStep_.

Referenced by BlockFlow_test::adjustEpochs(), and BlockFlow< CONF >::AllocatorHandle::claimSlot().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ markEpochUnderflow()

template<class CONF = blockFlow::DefaultConfig>

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.

References BlockFlow< CONF >::adjustEpochStep(), Strategy< CONF >::averageEpochs(), Strategy< CONF >::boostFactor(), BlockFlow< CONF >::config(), and BlockFlow< CONF >::epochStep_.

Referenced by BlockFlow_test::adjustEpochs(), and BlockFlow< CONF >::discardBefore().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ announceAdditionalFlow()

template<class CONF = blockFlow::DefaultConfig>

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.

References BlockFlow< CONF >::_cache_timeStep_cutOff, BlockFlow< CONF >::epochStep_, Strategy< CONF >::framesPerEpoch(), and util::max().

Referenced by BlockFlow_test::announceLoad(), and ActivityLang::announceLoad().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ firstEpoch()

template<class CONF = blockFlow::DefaultConfig>

Epoch & firstEpoch ( )

inlineprivate

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

References BlockFlow< CONF >::alloc_, BlockFlow< CONF >::asEpoch(), and ExtentFamily< T, siz >::begin().

Referenced by BlockFlow< CONF >::discardBefore(), FlowDiagnostic< CONF >::first(), and BlockFlow< CONF >::until().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ lastEpoch()

template<class CONF = blockFlow::DefaultConfig>

Epoch & lastEpoch ( )

inlineprivate

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

References BlockFlow< CONF >::alloc_, BlockFlow< CONF >::asEpoch(), and ExtentFamily< T, siz >::last().

Referenced by BlockFlow< CONF >::AllocatorHandle::claimSlot(), FlowDiagnostic< CONF >::last(), and BlockFlow< CONF >::until().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ allEpochs()

template<class CONF = blockFlow::DefaultConfig>

EpochIter allEpochs ( )

inlineprivate

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

References BlockFlow< CONF >::alloc_, and ExtentFamily< T, siz >::begin().

Referenced by FlowDiagnostic< CONF >::allEpochs(), FlowDiagnostic< CONF >::cntElm(), BlockFlow< CONF >::discardBefore(), and FlowDiagnostic< CONF >::find().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ updatePastDeadline()

template<class CONF = blockFlow::DefaultConfig>

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.

References Time::ANYTIME, BlockFlow< CONF >::epochStep_, and BlockFlow< CONF >::pastDeadline_.

Referenced by BlockFlow< CONF >::discardBefore().

Here is the caller graph for this function:

◆ ___sanityCheckAlloc()

template<class CONF = blockFlow::DefaultConfig>

void ___sanityCheckAlloc ( size_t newBlockCnt )

inlineprivate

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

References vault::gear::blockFlow::BLOCK_EXPAND_SAFETY_LIMIT, and util::showSize().

Referenced by BlockFlow< CONF >::until().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ config()

template<class CONF = blockFlow::DefaultConfig>

CONF const & config ( ) const

inline

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

Referenced by BlockFlow< CONF >::markEpochUnderflow().

Here is the caller graph for this function:

Member Data Documentation

◆ EPOCH_SIZ

template<class CONF = blockFlow::DefaultConfig>

constexpr size_t EPOCH_SIZ = CONF::EPOCH_SIZ

staticconstexprprivate

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

◆ alloc_

template<class CONF = blockFlow::DefaultConfig>

Allocator alloc_

private

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

Referenced by BlockFlow< CONF >::allEpochs(), FlowDiagnostic< CONF >::allEpochs(), FlowDiagnostic< CONF >::cntEpochs(), BlockFlow< CONF >::discardBefore(), BlockFlow< CONF >::firstEpoch(), BlockFlow< CONF >::lastEpoch(), FlowDiagnostic< CONF >::poolSize(), and BlockFlow< CONF >::until().

◆ epochStep_

template<class CONF = blockFlow::DefaultConfig>

TimeVar epochStep_

private

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

Referenced by BlockFlow< CONF >::adjustEpochStep(), BlockFlow< CONF >::announceAdditionalFlow(), BlockFlow< CONF >::getEpochStep(), BlockFlow< CONF >::markEpochOverflow(), BlockFlow< CONF >::markEpochUnderflow(), BlockFlow< CONF >::until(), and BlockFlow< CONF >::updatePastDeadline().

◆ _cache_timeStep_cutOff

template<class CONF = blockFlow::DefaultConfig>

Duration _cache_timeStep_cutOff = Strategy::timeStep_cutOff()

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

Referenced by BlockFlow< CONF >::announceAdditionalFlow(), and BlockFlow< CONF >::markEpochOverflow().

◆ _cache_boostFactorOverflow

template<class CONF = blockFlow::DefaultConfig>

double _cache_boostFactorOverflow = Strategy::boostFactorOverflow()

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

Referenced by BlockFlow< CONF >::markEpochOverflow().

◆ pastDeadline_

template<class CONF = blockFlow::DefaultConfig>

TimeVar pastDeadline_ {Time::ANYTIME}

private

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

Referenced by BlockFlow< CONF >::updatePastDeadline().

Friends And Related Symbol Documentation

◆ FlowDiagnostic< CONF >

template<class CONF = blockFlow::DefaultConfig>

friend class FlowDiagnostic< CONF >

friend

„backdoor“ to watch internals from tests

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

Classes

Public Types

Public Attributes

Public Member Functions

Friends

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Constructor & Destructor Documentation

◆ BlockFlow()

Member Typedef Documentation

◆ Allocator

◆ Strategy

◆ RawIter

◆ Extent

◆ Epoch

◆ EpochIter

Member Function Documentation

◆ asEpoch()

◆ getEpochStep()

◆ adjustEpochStep()

◆ until()

◆ discardBefore()

◆ markEpochOverflow()

◆ markEpochUnderflow()

◆ announceAdditionalFlow()

◆ firstEpoch()

◆ lastEpoch()

◆ allEpochs()

◆ updatePastDeadline()

◆ ___sanityCheckAlloc()

◆ config()

Member Data Documentation

◆ EPOCH_SIZ

◆ alloc_

◆ epochStep_

◆ _cache_timeStep_cutOff

◆ _cache_boostFactorOverflow

◆ pastDeadline_

Friends And Related Symbol Documentation

◆ FlowDiagnostic< CONF >