Merge pull request #84 from bxparks/develop

merge v1.9.0 into master

Author: bxparks

.github/workflows/aunit_tests.yml

@@ -16,12 +16,16 @@ jobs:
 
     - name: Setup
       run: |
+        sudo apt update
+        sudo apt install -y libcurl4-openssl-dev
         cd ..
+        git clone https://github.com/HowardHinnant/date
         git clone https://github.com/bxparks/EpoxyDuino
         git clone https://github.com/bxparks/AceRoutine
         git clone https://github.com/bxparks/AUnit
         git clone https://github.com/bxparks/AceCommon
         git clone https://github.com/bxparks/AceWire
+        git clone https://github.com/bxparks/AceSorting
 
     - name: Verify examples
       run: |

.github/workflows/validation.yml

@@ -9,7 +9,7 @@ on: [push]
 jobs:
   build:
 
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-20.04
 
     # Tried to use
     # https://github.com/actions/checkout#Checkout-multiple-repos-side-by-side,
@@ -29,14 +29,15 @@ jobs:
         git clone https://github.com/bxparks/EpoxyDuino
         git clone https://github.com/bxparks/AUnit
         git clone https://github.com/bxparks/AceCommon
+        git clone https://github.com/bxparks/AceSorting
         git clone https://github.com/bxparks/AceTimeTools
         git clone https://github.com/bxparks/AceTimePython
         git clone https://github.com/bxparks/AceTimeValidation
         git clone https://github.com/eggert/tz
         git clone https://github.com/HowardHinnant/date
 
     - name: Set up Python 3.7
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v2
       with:
         python-version: '3.7'
 
@@ -60,19 +61,14 @@ jobs:
       run: |
         make -C ../AceTimeTools/compare_cpp
 
-    # Run just BasicHinnantDateTest and ExtendedHinnantDateTest. When a new
-    # TZDB version comes out, the Python pytz, dateutil, and Java validation
-    # tests will always fail because they depend on the obsolete TZ database on
-    # the hosted Operating System.
+    # Run the validations from AceTimeValidations (BasicHinnantDateTest,
+    # ExtendedHinnantDateTest, BasicAcetzTest, ExtendedAcetzTest). We don't run
+    # the others because when a new TZDB version comes out, the Python pytz,
+    # dateutil, and Java validation tests will fail because they depend
+    # on the obsolete TZ database on the host Operating System.
 
-    - name: BasicHinnantDateTest
+    - name: AceTimeValidation
       run: |
         cd ../AceTimeValidation
-        make -C BasicHinnantDateTest
-        make -C BasicHinnantDateTest runtests
-
-    - name: ExtendedHinnantDateTest
-      run: |
-        cd ../AceTimeValidation
-        make -C ExtendedHinnantDateTest
-        make -C ExtendedHinnantDateTest runtests
+        make validations
+        make runvalidations

CHANGELOG.md

@@ -1,6 +1,44 @@
 # Changelog
 
 * Unreleased
+* 1.9.0 (2021-12-02, TZDB 2021e)
+    * Add `ZoneSorterByName` and `ZoneSorterByOffsetAndName` classes
+      to sort zone indexes, ids, or names according to 2 pre-defined sorting
+      criteria: (1) by name, or (2) by UTC offset and then by name.
+        * See the [Zone Sorting](USER_GUIDE.md#ZoneSorting) section in the
+          `USER_GUIDE.md`.
+        * Adds a new dependency to
+          [AceSorting](https://github.com/bxparks/AceSorting) library.
+    * Add `examples/CompareAceTimeToHinnantDate` to compare the performance of
+      AceTime compared to Hinnant date library.
+        * AceTime seems to be about 90X faster for converting date-time
+          components to epoch seconds.
+    * Add `MaxBufSize` comment field into `zonedb[x]/zone_infos.h` which is the
+      maximum over all zones in that file. Must be less than or equal to
+      `ExtendedZoneProcessor::kMaxTransitions`.
+    * **Potential Breaking Change**: `class TransitionStorage`
+        * Rename `getHighWater()` to `getAllocSize()`. This now returns the
+          maximum number of transitions that has been allocated so far, which
+          happens to be `getHighWater() + 1`.
+        * Rename `resetHighWater()` to `resetAllocSize()`.
+        * Rename `ExtendedZoneProcessor::resetTransitionHighWater()` to
+          `resetTransitionAllocSize()`.
+        * All of these methods were intended for internal debugging so these
+          changes are not considered to be an API change.
+        * The semantics of these methods are now closer to the algorithm in
+          `AceTimePython/zone_processor.ZoneProcessor`.
+    * **Breaking Change**: Extract `BasicZoneProcessorCache` and
+      `ExtendedZoneProcessorCache` out of `BasicZoneManager` and
+      `ExtendedZoneManager`. Remove all pure `virtual` methods from
+      `ZoneManager`, making the class hierarchy non-polymorphic.
+        * Saves 1100-1300 bytes of flash on AVR processors.
+        * See [Migrating to v1.9](MIGRATING.md#MigratingToVersion190) for
+          migration info.
+    * **Breaking Change**: Remove pure `virtual` methods from `LinkManager`,
+      analogous to their removal from `ZoneManager`.
+        * Saves 68 bytes of flash on AVR processors.
+        * See [Migrating to v1.9](MIGRATING.md#MigratingToVersion190) for
+          migration info.
 * 1.8.2 (2021-10-28, TZDB 2021e)
     * Update to TZDB 2021e.
         * https://mm.icann.org/pipermail/tz-announce/2021-October/000069.html

DEVELOPER.md

@@ -626,16 +626,15 @@ tests will fail until the underlying timezone database of the OS is updated.
 <a name="ReleaseProcess"></a>
 ## Release Process
 
+* Update `examples/MemoryBenchmark` and `examples/AutoBenchmark`.
 * Update and commit the version numbers in various files:
     * `src/AceTime.h`
     * `README.md`
-    * `docs/date_time_timezone.md`
-    * `docs/clock_system_clock.md`
-    * `docs/installation.md`
-    * ...
+    * `USER_GUIDE.md`
+    * `MIGRATING.md`
+    * `CHANGELOG.md`
     * `docs/doxygen.cfg`
     * `library.properties`
-    * `CHANGELOG.md`
     * `$ git commit -m "..."`
 * Update and commit the Doxygen docs. This is done as a separate git commit
   because the Doxygen changes are often so large that they obscure all other
@@ -652,6 +651,17 @@ tests will fail until the underlying timezone database of the OS is updated.
     * Approve and merge the PR.
 * Create a new Release of AceTimePython.
     * Go to https://github.com/bxparks/AceTimePython
+    * Bump version number on `develop`.
+    * Merge `develop` into `master`.
+    * Click on "Releases"
+    * Click on "Draft a new release"
+    * Enter a tag version (e.g. `v1.2`), targeting the `master` branch.
+    * Enter the release title.
+    * Enter the release notes. I normally just copy and paste the latest changes
+      from `CHANGELOG.md`.
+    * Click Publish release.
+* Create a new Release of AceTimeTools.
+    * Go to https://github.com/bxparks/AceTimeTools
     * Click on "Releases"
     * Click on "Draft a new release"
     * Enter a tag version (e.g. `v1.2`), targeting the `master` branch.
@@ -668,10 +678,14 @@ tests will fail until the underlying timezone database of the OS is updated.
     * Enter the release notes. I normally just copy and paste the latest changes
       from `CHANGELOG.md`.
     * Click Publish release.
-* Add corresponding tags on AceTimeTools and AceTimeValidation for reference.
+* Add corresponding tags on AceTimePython, AceTimeTools and AceTimeValidation
+  for reference.
     * AceTimePython
         * `$ git tag -a 'atX.Y.Z' -m 'AceTime vX.Y.Z'`
         * `$ git push --tags`
+    * AceTimeTools
+        * `$ git tag -a 'atX.Y.Z' -m 'AceTime vX.Y.Z'`
+        * `$ git push --tags`
     * AceTimeValidation
         * `$ git tag -a 'atX.Y.Z' -m 'AceTime vX.Y.Z'`
         * `$ git push --tags`

MIGRATING.md

@@ -2,11 +2,184 @@
 
 ## Table of Contents
 
+* [Migrating to v1.9.0](#MigratingToVersion190)
+    * [Configuring the Zone Managers](#ConfiguringZoneManagers)
+    * [Using the Zone Managers](#UsingZoneManagers)
+    * [Link Managers](#LinkManagers)
 * [Migrating to v1.8.0](#MigratingToVersion180)
     * [Migrating to AceTimeClock](#MigratingToAceTimeClock)
     * [Migrating the DS3231Clock](#MigratingTheDS3231Clock)
     * [Migrating to LinkManagers](#MigratingToLinkManagers)
 
+<a name="MigratingToVersion190"></a>
+## Migrating to v1.9.0
+
+The `ZoneManager` hierarchy (containing `ManualZoneManager`, `BasicZoneManager`,
+and `ExtendedZoneManager`) was refactored from v1.8.0 to v1.9.0.
+
+<a name="ConfiguringZoneManagers"></a>
+### Configuring the Zone Managers
+
+In v1.8, the `ZoneManager` was an abstract interface class with 7 pure virtual
+methods that was the base class of the class hierarchy of all ZoneManager
+subclasses. This was convenient because the `TimeZone` related parts of the
+client application code could be written against the `ZoneManager` base class
+and the specific implementation could be configured in a small section of the
+application code. The problem with such a polymorphic class hierarchy is that
+the virtual methods consume significant amounts of flash memory, especially on
+8-bit AVR processors with limited flash. The
+[examples/MemoryBenchmark](examples/MemoryBenchmark) program showed that this
+design consumed an extra 1100-1300 bytes of flash.
+
+In v1.9, several changes were made to reduce the flash memory size:
+
+1. All virtual methods were removed from the `ZoneManager` and its
+   subclasses. 
+2. The `BasicZoneManager` and `ExtendedZoneManager` classes are no longer
+   template classes, making them easier to use (e.g. in the `ZoneSorterByName`
+   and `ZoneSorterByOffsetAndName` classes).
+3. The internal `BasicZoneProcessorCache` and `ExtendedZoneProcessorCache`
+   member variables were extracted out from the respective ZoneManager classes.
+   These are now expected to be created separately, and passed into the
+   constructors of the `BasicZoneManager` and `ExtendedZoneManager` classes.
+
+The migration path is relatively simple. In v1.8, the `BasicZoneManager` was
+configured like this:
+
+```C++
+static const uint8_t CACHE_SIZE = 4;
+BasicZoneManager<CACHE_SIZE> zoneManager(
+    kZoneRegistrySize,
+    kZoneRegistry);
+```
+
+In v1.9, this should be replaced with code that looks like:
+
+```C++
+static const uint8_t CACHE_SIZE = 4;
+BasicZoneProcessorCache<CACHE_SIZE> zoneProcessorCache;
+BasicZoneManager zoneManager(
+    kZoneRegistrySize,
+    kZoneRegistry,
+    zoneProcessorCache);
+```
+
+Similarly, in v1.8, the `ExtendedZoneManager` was configured like following:
+
+```C++
+static const uint8_t CACHE_SIZE = 4;
+ExtendedoneManager<CACHE_SIZE> zoneManager(
+    zonedb::kZoneRegistrySize,
+    zonedb::kZoneRegistry);
+```
+
+In v1.9, this should be replaced with code that looks like this:
+
+```C++
+static const uint8_t CACHE_SIZE = 4;
+ExtendedoneProcessorCache<CACHE_SIZE> zoneProcessorCache;
+ExtendedoneManager zoneManager(
+    zonedbx::kZoneRegistrySize,
+    zonedbx::kZoneRegistry,
+    zoneProcessorCache);
+```
+
+<a name="UsingZoneManagers"></a>
+### Using the Zone Managers
+
+In v1.8, the `ZoneManager` was the parent interface class of all polymorphic
+subclasses. So the client code that needed a specific subclass of `ZoneManager`
+could do something like this:
+
+```C++
+class Controller {
+  public:
+    Controller(
+      ZoneManager* zoneManager,
+      ...
+    ) :
+      mZoneManager(zoneManager),
+      ...
+    {}
+
+  private:
+    ZoneManager* mZoneManager;
+};
+```
+
+Any instance of `BasicZoneManager<SIZE>` or `ExtendedZoneManager<SIZE>` could be
+passed into the constructor. This provided some runtime flexibility and code
+simplicity. However, the runtime flexibility did not seem useful for the vast
+majority of cases and the simplicity offered by the single parent interface
+class was paid for by an extra 1100-1300 bytes of flash memory.
+
+In v1.9, the application still has the ability to choose between a
+`BasicZoneManager` and an `ExtendedZoneManager` at compile time. The same
+`Controller` constructor should look something like this:
+
+```C++
+// Define the various TIME_ZONE_TYPE macros in config.h.
+#include "config.h"
+
+class Controller {
+  public:
+    Controller(
+    #if TIME_ZONE_TYPE == TIME_ZONE_TYPE_BASIC
+      BasicZoneManager* zoneManager,
+    #elif TIME_ZONE_TYPE == TIME_ZONE_TYPE_EXTENDED
+      ExtendedZoneManager* zoneManager,
+    #endif
+      ...
+    ) :
+      mZoneManager(zoneManager),
+      ...
+    {}
+
+  private:
+  #if TIME_ZONE_TYPE == TIME_ZONE_TYPE_BASIC
+    BasicZoneManager* mZoneManager;
+  #elif TIME_ZONE_TYPE == TIME_ZONE_TYPE_EXTENDED
+    ExtendedZoneManager* mZoneManager;
+  #endif
+};
+```
+
+It is assumed that most applications will hard code either the
+`BasicZoneManager` or the `ExtendedZoneManager`, and will not need this level
+of configuration.
+
+<a name="LinkManagers"></a>
+### Link Managers
+
+In v1.8, the `LinkManager` was an interface class with pure virtual methods:
+
+```C++
+class LinkManager {
+  public:
+    static const uint16_t kInvalidZoneId = 0x0;
+    virtual uint32_t zoneIdForLinkId(uint32_t linkId) const = 0;
+    virtual uint16_t linkRegistrySize() const = 0;
+};
+```
+
+But allowing the `BasicLinkManager` and `ExtendedLinkManager` to be polymorphic
+did not seem worth the extra flash usage, similar to the `ZoneManager`
+hierarchy.
+
+In v1.9, the pure `virtual` methods were removed, but the static constant
+was retained for backwards compatibility:
+
+```C++
+class LinkManager {
+  public:
+    static const uint16_t kInvalidZoneId = 0x0;
+};
+```
+
+The `BasicLinkManager` and `ExtendedLinkManager` should be used directly,
+instead of through the `LinkManager` interface. Since Link Managers were
+introduced only in v1.8, I expect almost no one to be affected by this.
+
 <a name="MigratingToVersion180"></a>
 ## Migrating to v1.8.0