AceTime
1.11.6
Date and time classes for Arduino that support timezones from the TZ Database.
|
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 Types | |
typedef TransitionTemplate< ZEB, ZPB, ZRB > | Transition |
Template instantiation of TransitionTemplate used by this class. More... | |
typedef MatchingTransitionTemplate< ZEB, ZPB, ZRB > | MatchingTransition |
Template instantiation of MatchingTransitiontemplate used by this class. More... | |
typedef TransitionResultTemplate< ZEB, ZPB, ZRB > | TransitionResult |
Template instantiation of TransitionResultTemplate 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... | |
MatchingTransition | findTransitionForSeconds (acetime_t epochSeconds) const |
Return the Transition matching the given epochSeconds. More... | |
TransitionResult | 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 uint8_t | calculateFold (acetime_t epochSeconds, const Transition *match, const Transition *prevMatch) |
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.
SIZE | size of internal cache |
ZEB | type of ZoneEraBroker |
ZPB | type of ZonePolicyBroker |
ZRB | type of ZoneRuleBroker |
Definition at line 507 of file ExtendedZoneProcessor.h.
typedef MatchingTransitionTemplate<ZEB, ZPB, ZRB> ace_time::extended::TransitionStorageTemplate< SIZE, ZEB, ZPB, ZRB >::MatchingTransition |
Template instantiation of MatchingTransitiontemplate used by this class.
This should be treated as a private, it is exposed only for testing purposes.
Definition at line 520 of file ExtendedZoneProcessor.h.
typedef TransitionTemplate<ZEB, ZPB, ZRB> ace_time::extended::TransitionStorageTemplate< SIZE, ZEB, ZPB, ZRB >::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 513 of file ExtendedZoneProcessor.h.
typedef TransitionResultTemplate<ZEB, ZPB, ZRB> ace_time::extended::TransitionStorageTemplate< SIZE, ZEB, ZPB, ZRB >::TransitionResult |
Template instantiation of TransitionResultTemplate used by this class.
This should be treated as a private, it is exposed only for testing purposes.
Definition at line 527 of file ExtendedZoneProcessor.h.
|
inline |
Add active candidates into the Active pool, and collapse the Candidate pool.
Every MatchingEra will have at least one Transition.
Definition at line 683 of file ExtendedZoneProcessor.h.
|
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 607 of file ExtendedZoneProcessor.h.
|
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 657 of file ExtendedZoneProcessor.h.
|
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 647 of file ExtendedZoneProcessor.h.
|
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 761 of file ExtendedZoneProcessor.h.
|
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 717 of file ExtendedZoneProcessor.h.
|
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 862 of file ExtendedZoneProcessor.h.
|
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 584 of file ExtendedZoneProcessor.h.
|
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 538 of file ExtendedZoneProcessor.h.
|
inline |
Verify that the indexes are valid.
Used only for debugging.
Definition at line 822 of file ExtendedZoneProcessor.h.
|
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 622 of file ExtendedZoneProcessor.h.
|
inline |
Reset the current allocation size.
For debugging.
Definition at line 855 of file ExtendedZoneProcessor.h.
|
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 560 of file ExtendedZoneProcessor.h.