AceTime  0.5
Date and time classes for Arduino that support timezones from the TZ Database, and a system clock that can synchronize from an NTP server or an RTC chip.
Public Member Functions | Friends | List of all members
ace_time::extended::TransitionStorage< SIZE > Class Template Reference

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

Public Member Functions

 TransitionStorage ()
 Constructor. More...
 
void init ()
 Initialize all pools. More...
 
TransitiongetPrior ()
 Return the current prior transition. More...
 
void swap (Transition **a, Transition **b)
 Swap 2 transitions. More...
 
void resetCandidatePool ()
 Empty the Candidate pool by resetting the various indexes. More...
 
Transition ** getCandidatePoolBegin ()
 
Transition ** getCandidatePoolEnd ()
 
Transition ** getActivePoolBegin ()
 
Transition ** getActivePoolEnd ()
 
TransitiongetFreeAgent ()
 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 one Transition just after the Active pool, but before the Candidate pool, to keep the most recent prior Transition. More...
 
void setFreeAgentAsPrior ()
 Swap the Free agrent transition with the current Prior transition. More...
 
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...
 
void addActiveCandidatesToActivePool ()
 Add active candidates into the Active pool, and collapse the Candidate pool.
 
const TransitionfindTransition (acetime_t epochSeconds) const
 Return the Transition matching the given epochSeconds. More...
 
const TransitionfindTransitionForDateTime (const LocalDateTime &ldt) const
 Return the Transition matching the given dateTime. More...
 
void log () const
 Verify that the indexes are valid. More...
 
void resetHighWater ()
 Reset the high water mark. More...
 
uint8_t getHighWater () const
 Return the high water mark. More...
 

Friends

class ::TransitionStorageTest_getFreeAgent
 
class ::TransitionStorageTest_getFreeAgent2
 
class ::TransitionStorageTest_addFreeAgentToActivePool
 
class ::TransitionStorageTest_reservePrior
 
class ::TransitionStorageTest_addFreeAgentToCandidatePool
 
class ::TransitionStorageTest_setFreeAgentAsPrior
 
class ::TransitionStorageTest_addActiveCandidatesToActivePool
 
class ::TransitionStorageTest_resetCandidatePool
 

Detailed Description

template<uint8_t SIZE>
class ace_time::extended::TransitionStorage< SIZE >

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 (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 pool: [mIndexFree, SIZE)

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.

Definition at line 347 of file ExtendedZoneProcessor.h.

Constructor & Destructor Documentation

◆ TransitionStorage()

template<uint8_t SIZE>
ace_time::extended::TransitionStorage< SIZE >::TransitionStorage ( )
inline

Constructor.

Definition at line 350 of file ExtendedZoneProcessor.h.

Member Function Documentation

◆ addFreeAgentToActivePool()

template<uint8_t SIZE>
void ace_time::extended::TransitionStorage< SIZE >::addFreeAgentToActivePool ( )
inline

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

Then increment mIndexFree to remove 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 421 of file ExtendedZoneProcessor.h.

◆ addFreeAgentToCandidatePool()

template<uint8_t SIZE>
void ace_time::extended::TransitionStorage< SIZE >::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.modifier).

Definition at line 459 of file ExtendedZoneProcessor.h.

◆ addPriorToCandidatePool()

template<uint8_t SIZE>
void ace_time::extended::TransitionStorage< SIZE >::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 449 of file ExtendedZoneProcessor.h.

◆ findTransition()

template<uint8_t SIZE>
const Transition* ace_time::extended::TransitionStorage< SIZE >::findTransition ( 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 tools/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 500 of file ExtendedZoneProcessor.h.

◆ findTransitionForDateTime()

template<uint8_t SIZE>
const Transition* ace_time::extended::TransitionStorage< SIZE >::findTransitionForDateTime ( const LocalDateTime ldt) const
inline

Return the Transition matching the given dateTime.

Return nullptr if no matching Transition found. During DST changes, a particlar LocalDateTime may correspond to 2 Transitions or 0 Transitions, and there are potentially multiple ways to handle this. This method implements the following algorithm:

1) If the localDateTime falls in the DST transition gap where 0 Transitions ought to be found, e.g. between 02:00 and 03:00 in America/Los_Angeles when standard time switches to DST time), the immediate prior Transition is returned (in effect extending the UTC offset of the prior Transition through the gap. For example, when DST starts, 02:00 becomes 03:00, so a time of 02:30 does not exist, but the Transition returned will be the one valid at 01:59. When it is converted to epoch_seconds and converted back to a LocalDateTime, the 02:30 time will become 03:30, since the later UTC offset will be used.

2) If the localDateTime falls in a time period where there are 2 Transitions, hence 2 valid UTC offsets, the later Transition is returned. For example, when DST ends in America/Los_Angeles, 02:00 becomes 01:00, so a time of 01:30 could belong to the earlier or later Transition. This method returns the later Transition.

Definition at line 536 of file ExtendedZoneProcessor.h.

◆ getFreeAgent()

template<uint8_t SIZE>
Transition* ace_time::extended::TransitionStorage< SIZE >::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 400 of file ExtendedZoneProcessor.h.

◆ getHighWater()

template<uint8_t SIZE>
uint8_t ace_time::extended::TransitionStorage< SIZE >::getHighWater ( ) const
inline

Return the high water mark.

This is the largest value of mIndexFree that was used. If this returns SIZE, it indicates that the Transition mPool overflowed. For debugging.

Definition at line 589 of file ExtendedZoneProcessor.h.

◆ getPrior()

template<uint8_t SIZE>
Transition* ace_time::extended::TransitionStorage< SIZE >::getPrior ( )
inline

Return the current prior transition.

Definition at line 363 of file ExtendedZoneProcessor.h.

◆ init()

template<uint8_t SIZE>
void ace_time::extended::TransitionStorage< SIZE >::init ( )
inline

Initialize all pools.

Definition at line 353 of file ExtendedZoneProcessor.h.

◆ log()

template<uint8_t SIZE>
void ace_time::extended::TransitionStorage< SIZE >::log ( ) const
inline

Verify that the indexes are valid.

Used only for debugging.

Definition at line 555 of file ExtendedZoneProcessor.h.

◆ reservePrior()

template<uint8_t SIZE>
Transition** ace_time::extended::TransitionStorage< SIZE >::reservePrior ( )
inline

Allocate one Transition just after the Active pool, but before the Candidate pool, to keep the most recent prior Transition.

Shift the Candidate pool and Free pool up by one.

Definition at line 433 of file ExtendedZoneProcessor.h.

◆ resetCandidatePool()

template<uint8_t SIZE>
void ace_time::extended::TransitionStorage< SIZE >::resetCandidatePool ( )
inline

Empty the Candidate pool by resetting the various indexes.

If every iteration of findTransitionsForMatch() 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 380 of file ExtendedZoneProcessor.h.

◆ resetHighWater()

template<uint8_t SIZE>
void ace_time::extended::TransitionStorage< SIZE >::resetHighWater ( )
inline

Reset the high water mark.

For debugging.

Definition at line 582 of file ExtendedZoneProcessor.h.

◆ setFreeAgentAsPrior()

template<uint8_t SIZE>
void ace_time::extended::TransitionStorage< SIZE >::setFreeAgentAsPrior ( )
inline

Swap the Free agrent transition with the current Prior transition.

Definition at line 440 of file ExtendedZoneProcessor.h.

◆ swap()

template<uint8_t SIZE>
void ace_time::extended::TransitionStorage< SIZE >::swap ( Transition **  a,
Transition **  b 
)
inline

Swap 2 transitions.

Definition at line 366 of file ExtendedZoneProcessor.h.


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