breaking changes in v1.3

[bxparks]

Folks,

I'm about to release v1.3 of AceRoutine, but it has a number of API breaking changes. The primary motivation for v1.3 is to reduce the flash memory consumption of a Coroutine instance as much as possible, particularly on 8-bit AVR processors, while retaining its core functionality.

• In v1.2.4, the first instance of Coroutine consumes 1098 bytes of flash, and the subsequent instances consume about 228 bytes of flash each.
• In v1.3, the first instance consumes 234 bytes of flash, and each subsequent instance takes an additional 170 bytes of flash.
• Static memory usage goes down as well, from ~30 bytes/instance to 17 bytes/instance.

Here are the breaking changes that reduced the resource consumption:

1. The destructor in the Coroutine class is no longer virtual. This means that Coroutine instance cannot be created on the heap using the new operator, and cannot be deleted polymorphically. I don't think this will be a problem because this usage has never been tested, and was not documented. This single change decreases flash usage on an AVR processor by about 600 bytes because the virtual destructor pulls in malloc() and free().

2. The COROUTINE_DELAY_MICROS() micro has been deleted. I personally have never used this feature. I implemented it in Microsecond Timing? #9, but in retrospect, it was a mistake. Because it forces the COROUTINE_DELAY() to use a switch statement, which increases flash usage by about 30 bytes on every usage of COROUTINE_DELAY(), even if COROUTINE_DELAY_MICROS() is never used in a given program.

3. The COROUTINE_DELAY_SECONDS() macro has been deleted. This saves 150-200 bytes of flash on the 1st coroutine, and 10-30 bytes of flash per subsequent instance. This macro uses a division by 1000 operation on a 32-bit millisecond integer counter to keep track of the "seconds". On an 8-bit AVR processor with no hardware division instruction, a software long division on a 32-bit integer is very expensive.

4. The Coroutine class no longer saves the human readable name of the coroutine, by removing the Coroutine::mName field and the Coroutine::getName() method. This saves about 10-30 bytes of flash (depending on the length of the name string), and 3 bytes of static memory per Coroutine instance. I had thought that saving the human-readable name would be helpful for debugging, in combination of the CoroutineScheduler::list() function. But in practice, it has not been very useful, and I don't think it's worth paying the extra resource cost.

5. Updated: With the removal of Coroutine::mName, the Coroutine::setupCoroutine() no longer needs to be called, because the human-readable name no longer needs to be provided through the setupCoroutine() method. This method is now marked deprecated, but retained for backwards compatibility. The compiler will print a warning message.

6. Updated: The Coroutine::coroutineMillis() method is no longer virtual. The only reason this method was marked as virtual was to allow the injection of a fake millis() function for unit testing purposes. Using some C++ template magic, I am able to use compile-time polymorphism, instead of runtime polymorphism through the virtual dispatch, saving 15-25 bytes of flash (I think per each usage of COROUTINE_DELAY(), but I'm not sure), yet, still be able to inject a fake millis() for unit tests. The nice thing about a non-virtual coroutineMillis() is that the compiler is able to completely optimize away the extra function call. So the coroutineMillis() call becomes optimized into a direct call to millis().

In general, a Coroutine will always have a higher overhead than a simple function with a non-blocking delay on a millis() function. But sometimes, an algorithm is far easier to express as a coroutine than using a finite state machine inside a non-blocking function, see USER_GUIDE.md#ComparisonToNonBlockingFunction and the benchmark results in MemoryBenchmark/README.md.

I am hoping with the changes made in v1.3, the overhead of the Coroutine class is small enough that the tradeoff become more worthwhile in more situations.

[bxparks]

I just released v1.3.1 after I figured out how to implement COROUTINE_DELAY_MICROS() and COROUTINE_DELAY_SECONDS() so that they increase flash and static memory consumption only if they are used.

The Coroutine now figures out the meaning of mDelayStart and mDelayDuration with different units without suffering from the runtime overhead of a mDelayType discriminator. The coroutine implicitly knows which unit to use because when it returns to its continuation point, it knows which macro was called. The implementation also changes CoroutineScheduler so that it always calls Coroutine::runCoroutine() to handle the isDelayXxxExpired() test, instead of trying to avoid the extra function call. This actually simplifies the code for CoroutineScheduler.

The MemoryBenchmark shows that COROUTINE_DELAY_MICROS() consumes slightly smaller flash memory than COROUTINE_DELAY(), probably because there is some overhead in the Arduino millis() compared to micros(). The COROUTINE_DELAY_SECONDS() pulls in a long division by 1000. On AVR processors, this increases flash by ~100 bytes. On 32-bit processors with hardware integer division, there is very little change in flash memory.

On AVR processors, the extra call into Coroutine::runCoroutine() makes the CoroutineScheduler::loop() slightly slower. But on 32-bit processors, it actually makes the CoroutineScheduler::loop() faster. See AutoBenchmark. Not sure why.

In summary, the API breakages from v1.2.4 to v1.3.1 should be fairly minor:

1)) No virtual destructor on Coroutine.
4)) No human readable Coroutine::getName().
5)) Coroutine::setupCoroutine() is no longer required to be called and is marked deprecated.
6)) Coroutine::coroutineMillis(), Coroutine::coroutineMicros(), Coroutine::coroutineSeconds() are no longer virtual.