A heap manager which is specialized and tuned to manage a collection of Transitions, keeping track of unused, used, and active states, using a fixed array of Transitions. More...

#include <Transition.h>

Public Types
typedef TransitionTemplate< D >	Transition
	Template instantiation of TransitionTemplate used by this class. More...

typedef TransitionForSecondsTemplate< D >	TransitionForSeconds
	Template instantiation of TransitionForSecondsTemplate used by this class. More...

typedef TransitionForDateTimeTemplate< D >	TransitionForDateTime
	Template instantiation of TransitionForDateTimeTemplate used by this class. More...

Public Member Functions
	TransitionStorageTemplate ()
	Constructor.

void	init ()
	Initialize all pools to 0 size, usually when a new year is initialized. More...

Transition *	getPrior ()
	Return the current prior transition.

void	resetCandidatePool ()
	Empty the Candidate pool by resetting the various indexes. More...

Transition **	getCandidatePoolBegin ()

Transition **	getCandidatePoolEnd ()

Transition **	getActivePoolBegin ()

Transition **	getActivePoolEnd ()

Transition *	getFreeAgent ()
	Return a pointer to the first Transition in the free pool. More...

void	addFreeAgentToActivePool ()
	Immediately add the free agent Transition at index mIndexFree to the Active pool. More...

Transition **	reservePrior ()
	Allocate a free Transition then add it to the Prior pool. More...

void	setFreeAgentAsPriorIfValid ()
	Set the free agent transition as the most recent prior.

void	addPriorToCandidatePool ()
	Add the current prior into the Candidates pool. More...

void	addFreeAgentToCandidatePool ()
	Add the free agent Transition at index mIndexFree to the Candidate pool, sorted by transitionTime. More...

Transition *	addActiveCandidatesToActivePool ()
	Add active candidates into the Active pool, and collapse the Candidate pool. More...

TransitionForSeconds	findTransitionForSeconds (acetime_t epochSeconds) const
	Return the Transition matching the given epochSeconds. More...

TransitionForDateTime	findTransitionForDateTime (const LocalDateTime &ldt) const
	Return the candidate Transitions matching the given dateTime. More...

void	log () const
	Verify that the indexes are valid. More...

void	resetAllocSize ()
	Reset the current allocation size. More...

uint8_t	getAllocSize () const
	Return the maximum number of transitions which was allocated. More...

Static Public Member Functions
static void	calcFoldAndOverlap (uint8_t fold, uint8_t num, const Transition prev, const Transition curr, const Transition *next, acetime_t epochSeconds)
	Calculate the fold and num parameters of TransitionForSecond. More...

Friends
class	::TransitionStorageTest_getFreeAgent

class	::TransitionStorageTest_getFreeAgent2

class	::TransitionStorageTest_addFreeAgentToActivePool

class	::TransitionStorageTest_reservePrior

class	::TransitionStorageTest_addPriorToCandidatePool

class	::TransitionStorageTest_addFreeAgentToCandidatePool

class	::TransitionStorageTest_setFreeAgentAsPriorIfValid

class	::TransitionStorageTest_addActiveCandidatesToActivePool

class	::TransitionStorageTest_findTransitionForDateTime

class	::TransitionStorageTest_resetCandidatePool

Detailed Description

template<uint8_t SIZE, typename D>
class ace_time::extended::TransitionStorageTemplate< SIZE, D >

A heap manager which is specialized and tuned to manage a collection of Transitions, keeping track of unused, used, and active states, using a fixed array of Transitions.

Its main purpose is to provide some illusion of dynamic memory allocation without actually performing any dynamic memory allocation.

We create a fixed sized array for the total pool, determined by the template parameter SIZE, then manage the various sub-pools of Transition objects. The allocation of the various sub-pools is intricately tied to the precise pattern of creation and release of the various Transition objects within the ExtendedZoneProcessor class.

There are 4 pools indicated by the following half-open (inclusive to exclusive) index ranges:

1) Active pool: [0, mIndexPrior) 2) Prior pool: [mIndexPrior, mIndexCandidates), either 0 or 1 element 3) Candidate pool: [mIndexCandidates, mIndexFree) 4) Free agent pool: [mIndexFree, mAllocSize), 0 or 1 element

At the completion of the ExtendedZoneProcessor::init(LocalDate& ld) method, the Active pool will contain the active Transitions relevant to the 'year' defined by the LocalDate. The Prior and Candidate pools will be empty, with the Free pool taking up the remaining space.

Template Parameters

SIZE	size of internal cache
D	container type of ZoneInfo database

Definition at line 351 of file Transition.h.

Member Typedef Documentation

◆ Transition

template<uint8_t SIZE, typename D >

typedef TransitionTemplate<D> ace_time::extended::TransitionStorageTemplate< SIZE, D >::Transition

Template instantiation of TransitionTemplate used by this class.

This should be treated as a private, it is exposed only for testing purposes.

Definition at line 357 of file Transition.h.

◆ TransitionForDateTime

template<uint8_t SIZE, typename D >

typedef TransitionForDateTimeTemplate<D> ace_time::extended::TransitionStorageTemplate< SIZE, D >::TransitionForDateTime

Template instantiation of TransitionForDateTimeTemplate used by this class.

This should be treated as a private, it is exposed only for testing purposes.

Definition at line 371 of file Transition.h.

◆ TransitionForSeconds

template<uint8_t SIZE, typename D >

typedef TransitionForSecondsTemplate<D> ace_time::extended::TransitionStorageTemplate< SIZE, D >::TransitionForSeconds

Template instantiation of TransitionForSecondsTemplate used by this class.

This should be treated as a private, it is exposed only for testing purposes.

Definition at line 364 of file Transition.h.

Member Function Documentation

◆ addActiveCandidatesToActivePool()

template<uint8_t SIZE, typename D >

Transition* ace_time::extended::TransitionStorageTemplate< SIZE, D >::addActiveCandidatesToActivePool ( )

inline

Add active candidates into the Active pool, and collapse the Candidate pool.

Every MatchingEra will have at least one Transition.

Returns: the last Transition that was added

Definition at line 527 of file Transition.h.

◆ addFreeAgentToActivePool()

template<uint8_t SIZE, typename D >

void ace_time::extended::TransitionStorageTemplate< SIZE, D >::addFreeAgentToActivePool ( )

inline

Immediately add the free agent Transition at index mIndexFree to the Active pool.

Then increment mIndexFree to consume the free agent from the Free pool. This assumes that the Pending and Candidate pool are empty, which makes the Active pool come immediately before the Free pool.

Definition at line 451 of file Transition.h.

◆ addFreeAgentToCandidatePool()

template<uint8_t SIZE, typename D >

void ace_time::extended::TransitionStorageTemplate< SIZE, D >::addFreeAgentToCandidatePool ( )

inline

Add the free agent Transition at index mIndexFree to the Candidate pool, sorted by transitionTime.

Then increment mIndexFree by one to remove the free agent from the Free pool. Essentially this is an Insertion Sort keyed by the 'transitionTime' (ignoring the DateTuple.suffix).

Definition at line 501 of file Transition.h.

◆ addPriorToCandidatePool()

template<uint8_t SIZE, typename D >

void ace_time::extended::TransitionStorageTemplate< SIZE, D >::addPriorToCandidatePool ( )

inline

Add the current prior into the Candidates pool.

Prior is always just before the start of the Candidate pool, so we just need to shift back the start index of the Candidate pool.

Definition at line 491 of file Transition.h.

◆ calcFoldAndOverlap()

template<uint8_t SIZE, typename D >

static void ace_time::extended::TransitionStorageTemplate< SIZE, D >::calcFoldAndOverlap	(	uint8_t *	fold,
		uint8_t *	num,
		const Transition *	prev,
		const Transition *	curr,
		const Transition *	next,
		acetime_t	epochSeconds
	)

inlinestatic

Calculate the fold and num parameters of TransitionForSecond.

The num parameter is the number of transitions which can shadow a given epochSeconds. It is 0 if curr is NULL, which means that epochSeconds cannot be mapped to any transition. It is 1 if the epochSeconds in the curr transition is unique and does not overlap with the prev or next transition. It is 2 if the epochSeconds in the curr transition maps to a LocalDateTime that overlaps with either the prev or next transition. (In theory, I suppose it could overlap with both, but it is improbable that any timezone in the TZDB will ever let that happen.)

The fold parameter specifies whether the curr transition is the first instance (0) or the second instance (1). It is relevant only if num is

If num is 0 or 1, fold will always be 0. If num is 2, then fold indicates whether curr is the earlier (0) or later (1) transition of the overlap. This fold parameter will be copied into the corresponding fold parameter in LocalDateTime.

Definition at line 606 of file Transition.h.

◆ findTransitionForDateTime()

template<uint8_t SIZE, typename D >

TransitionForDateTime ace_time::extended::TransitionStorageTemplate< SIZE, D >::findTransitionForDateTime ( const LocalDateTime & ldt ) const

inline

Return the candidate Transitions matching the given dateTime.

The search may return 0, 1 or 2 Transitions, depending on whether the dateTime falls in a gap or overlap.

Definition at line 677 of file Transition.h.

◆ findTransitionForSeconds()

template<uint8_t SIZE, typename D >

TransitionForSeconds ace_time::extended::TransitionStorageTemplate< SIZE, D >::findTransitionForSeconds ( acetime_t epochSeconds ) const

inline

Return the Transition matching the given epochSeconds.

Return nullptr if no matching Transition found. If a zone does not have any transition according to TZ Database, the AceTimeTools/transformer.py script adds an "anchor" transition at the "beginning of time" which happens to be the year 1872 (because the year is stored as an int8_t). Therefore, this method should never return a nullptr for a well-formed ZoneInfo file.

Definition at line 561 of file Transition.h.

◆ getAllocSize()

template<uint8_t SIZE, typename D >

uint8_t ace_time::extended::TransitionStorageTemplate< SIZE, D >::getAllocSize ( ) const

inline

Return the maximum number of transitions which was allocated.

If this is greater than SIZE, it indicates that the Transition mPool overflowed. This method is intended for debugging.

Definition at line 766 of file Transition.h.

◆ getFreeAgent()

template<uint8_t SIZE, typename D >

Transition* ace_time::extended::TransitionStorageTemplate< SIZE, D >::getFreeAgent ( )

inline

Return a pointer to the first Transition in the free pool.

If this transition is not used, then it's ok to just drop it. The next time getFreeAgent() is called, the same Transition will be returned.

Definition at line 428 of file Transition.h.

◆ init()

template<uint8_t SIZE, typename D >

void ace_time::extended::TransitionStorageTemplate< SIZE, D >::init ( )

inline

Initialize all pools to 0 size, usually when a new year is initialized.

The mAllocSize is not reset, so that we can determine the maximum allocation size across multiple years. Call resetAllocSize() manually to reset the mAllocSize.

Definition at line 382 of file Transition.h.

◆ log()

template<uint8_t SIZE, typename D >

void ace_time::extended::TransitionStorageTemplate< SIZE, D >::log ( ) const

inline

Verify that the indexes are valid.

Used only for debugging.

Definition at line 733 of file Transition.h.

◆ reservePrior()

template<uint8_t SIZE, typename D >

Transition** ace_time::extended::TransitionStorageTemplate< SIZE, D >::reservePrior ( )

inline

Allocate a free Transition then add it to the Prior pool.

This assumes that the Prior pool and Candidate pool were both empty before calling this method. Shift the Candidate pool and Free pool up by one. Return a handle (pointer to pointer) to the Transition, so that the prior Transition can be swapped with another Transition, while keeping the handle valid.

Definition at line 466 of file Transition.h.

◆ resetAllocSize()

template<uint8_t SIZE, typename D >

void ace_time::extended::TransitionStorageTemplate< SIZE, D >::resetAllocSize ( )

inline

Reset the current allocation size.

For debugging.

Definition at line 759 of file Transition.h.

◆ resetCandidatePool()

template<uint8_t SIZE, typename D >

void ace_time::extended::TransitionStorageTemplate< SIZE, D >::resetCandidatePool ( )

inline

Empty the Candidate pool by resetting the various indexes.

If every iteration of createTransitionsForMatch() finishes with addFreeAgentToActivePool() or addActiveCandidatesToActivePool(), it may be possible to remove this. But it's safer to reset the indexes upon each iteration.

Definition at line 404 of file Transition.h.

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

/home/brian/src/AceTimeSuite/libraries/AceTimeLib/src/ace_time/Transition.h

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

template<uint8_t SIZE, typename D> class ace_time::extended::TransitionStorageTemplate< SIZE, D >

Member Typedef Documentation

◆ Transition

◆ TransitionForDateTime

◆ TransitionForSeconds

Member Function Documentation

◆ addActiveCandidatesToActivePool()

◆ addFreeAgentToActivePool()

◆ addFreeAgentToCandidatePool()

◆ addPriorToCandidatePool()

◆ calcFoldAndOverlap()

◆ findTransitionForDateTime()

◆ findTransitionForSeconds()

◆ getAllocSize()

◆ getFreeAgent()

◆ init()

◆ log()

◆ reservePrior()

◆ resetAllocSize()

◆ resetCandidatePool()

template<uint8_t SIZE, typename D>
class ace_time::extended::TransitionStorageTemplate< SIZE, D >