Merge pull request #30 from bxparks/develop

merge v1.3 into master

Author: bxparks

CHANGELOG.md

@@ -1,6 +1,80 @@
 # Changelog
 
 * Unreleased
+* 1.3.0 (2021-06-02)
+    * Activate GitHub Discussions for the project.
+    * **Potentially Breaking**: Change `Coroutine` destructor from virtual to
+      non-virtual.
+        * Saves 500-600 bytes on AVR processors, 350 bytes on SAMD21, and 50-150
+          bytes on other 32-bit processors. 
+        * Coroutines can now be created only statically, not dynamically on the
+          heap.
+    * **Potentially Breaking**: Lift `Coroutine` into `CoroutineTemplate` class.
+      Lift `CoroutineScheduler` into `CoroutineSchedulerTemplate` class.
+        * Define `Coroutine` to be `CoroutineTemplate<ClockInterface>`, almost
+        * fully backwards compatible with previous implementation.
+        * Define `CoroutineScheduler` to be
+          `CoroutineSchedulerTemplate<Coroutine>`, almost fully backwards
+          compatible with previous implementation.
+        * All macros (e.g. `COROUTINE()`, `COROUTINE_DELAY()`,
+          `COROUTINE_YIELD()`, etc) should work as before.
+        * Replace the 3 clock virtual methods on
+          `Coroutine` (`coroutineMicros()`, `coroutineMillis()`,
+          `coroutineSeconds()`) with a injectable `ClockInterface` template
+          parameter.
+        * **Breaking**: Convert `Coroutine::coroutineMicros()`,
+          `Coroutine::coroutineMillis()`, and `Coroutine::coroutineSeconds()`
+          into `private static` functions which delegate to
+          `ClockInterface::micros()`, `ClockInterface::millis()`, and
+          `ClockInterface::sesconds()`.
+        * Create `TestableClockInterface` for testing.
+        * Create `TestableCoroutine` for testing.
+        * Create `TestableCoroutineScheduler` for testing.
+        * Only 0-40 bytes of flash memory reduction on AVR processors, to my
+          surprise.
+        * But 100-1500 bytes of flash memory reduction on various 32-bit
+          processors.
+    * **Breaking**: Remove `COROUTINE_DELAY_SECONDS()`.
+        * Saves ~200 bytes on AVR processors, about 40%.
+        * Saves about 20-30 bytes on 32-bit processors.
+        * The replacement is a for-loop around a `COROUTINE_DELAY()`,
+          as shown in [USER_GUIDE.md#Delay](USER_GUIDE.md#Delay).
+    * **Breaking**: Remove `COROUTINE_DELAY_MICROS()`.
+        * Saves about 15-20 bytes of flash and 1 byte of static memory
+          per coroutine on AVR processors.
+        * Saves about 80-100 bytes of flash on 32-bit processors, plus an
+          additional 20-30 bytes of flash per coroutine on 32-bit processors.
+        * The `COROUTINE_DELAY_MICROS()` was never reliable because it depended
+          on other coroutines to release control of execution faster than the
+          value of the delay microseconds. This is very difficult to guarantee
+          in a cooperative multitasking environment.
+        * Removing this simplifies the code a fair amount.
+    * **Breaking**: Remove `Coroutine::getName()` and `Coroutine::mName`. The
+      human-readable name of the coroutine is no longer retained, to reduce
+      flash and static memory consumption.
+        * Remove `setupCoroutineOrderedByName()`, since it is no longer possible
+          to sort by name.
+        * Since we don't need to capture the name of the coroutine, we can
+          move `setupCoroutine()` functionality directly into
+          `Coroutine::Coroutine()` constructor.
+        * Deprecate `setupCoroutine(const char*)` and `setupCoroutine(const
+          __FlashStringHelper*)` into no-ops. They are retained for backwards
+          compatibility.
+        * Print the coroutine pointer address instead of its name in
+          `CoroutineScheduler::list()`, since the name is no longer retained.
+        * Saves 10-30 bytes of flash and 3 bytes of static memory per coroutine
+          instance on AVR.
+        * Saves 10-40 bytes of flash and 8 bytes of static memory per coroutine
+          instance on 32-bit processors.
+    * Blacklist platforms using the https://github.com/arduino/ArduinoCore-api
+      to give a user-friendly message instead of pages and pages of compiler
+      errors.
+    * Update
+      [Direct Scheduling or CoroutineScheduler](USER_GUIDE.md#DirectOrAutomatic)
+      section to recommend direct calls to `Coroutine::runCoroutine()` on 8-bit
+      processors, and limit the `CoroutineScheduler` to 32-bit processors with
+      sufficient flash memory.
+    * Add preliminary support for ATtiny85.
 * 1.2.4 (2021-01-22)
     * Update UnixHostDuino 0.4 to EpoxyDuino 0.5.
     * No functional change in this release.

DEVELOPER.md

@@ -6,8 +6,7 @@ even I have trouble remembering.
 ## Coroutine Linked List
 
 The `COROUTINE()` macro creates an instance of `Coroutine` whose constructor
-calls `setupCoroutine(const char* name)`. The `setupCoroutine()` method inserts
-the coroutine instance into a singly linked list. This allows the
+inserts the coroutine instance into a singly linked list. This allows the
 `CoroutineScheduler` to iterate over the linked list and allow the coroutines to
 execute in a round-robin fashion.