Merge pull request #22 from bxparks/develop

v1.2.1 - add DEVELOPER.md notes

Author: bxparks

CHANGELOG.md

@@ -1,6 +1,11 @@
 # Changelog
 
 * Unreleased
+* 1.2.1 (2020-11-12)
+    * Add `DEVELOPER.md` notes to myself. 
+    * Add python script to generate the README.md in
+      [examples/MemoryBenchmarks](examples/MemoryBenchmarks) to automatically
+      regenerate the embedded ascii tables. Regenerate README.md for v1.2.
 * 1.2 (2020-11-10)
     * Fix an infinite loop in the internal singly-linked list of coroutines when
       `resume()` is called immediately after `suspend()`, without waiting for

DEVELOPER.md

@@ -0,0 +1,64 @@
+# Developer Notes
+
+Information useful to developers of this library. In other words, things that
+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
+`CoroutineScheduler` to iterate over the linked list and allow the coroutines to
+execute in a round-robin fashion.
+
+It always takes me a few minutes to understand how I implemented the singly
+linked list, so here are some notes to myself.
+
+Each instance of `Coroutine` contains an `mNext` variable that points to the
+next instance of `Coroutine`. The last instance has an `mNext` that contains a
+`nullptr`.
+
+```
+            getRoot()         Coroutine         Coroutine
+            +--------+        +--------+       +--------+
+            |        |    --->|        |    -->|        |     --> nullptr
+            |        |   /    |        |   /   |        |    /
+            | root-------     | mNext------    | mNext-------
+            +-^------+        +-^------+       +-^------+
+Coroutine     |                /                /
+Scheduler     |               /                /
++---------+   |              /                /
+|         |   |             /                /
+|mCurrent------------------------------------
++---------+
+```
+
+The first element of the linked list is defined by the pointer stored in a
+static variable called `root` inside the `Coroutine::getRoot()` static function.
+Static variables inside functions are guaranteed to be initialized only once
+upon the first call to `getRoot()` and will be initialized to the default value
+of the type (`nullptr` in this case).
+
+The `CoroutineScheduler` uses a variable called `mCurrent` to keep track of the
+`Coroutine` which is currently being handled. The important part is to realize
+that `mCurrent` does *not* hold a pointer to `Coroutine` (i.e. `Coroutine*`) but
+it holds a pointer to a pointer to `Coroutine` (i.e. `Coroutine**`). Similarly,
+`Coroutine::getRoot()` returns a *pointer* to the `root` (i.e. `Coroutine**`),
+not the value of `root` (i.e. `Coroutine*`).
+
+Using the pointer to a pointer (i.e. `Coroutine**`) to represent the "current"
+coroutine has a number of advantages and simplifies the code that traverses the
+linked list.
+
+* The root node can be treated the same as a regular `Coroutine` node.
+    * See `CoroutineScheduler::listCoroutines()` to see this in action.
+* It allows new nodes to be inserted just after the "current" node.
+    * The `mCurrent` points to the `mNext` of the previous node, so with just a
+      single pointer, both the previous node and the current node can be
+      modified. If the "current" node was represented by a `Coroutine*`, it
+      would not be possible to update the previous node because this is a singly
+      linked list.
+    * See `Coroutine::insertAtRoot()` and `Coroutine::insertSorted()` to see how
+      this work.
+* It also allows the "current" node to be deleted from the linked list, although
+  this capability is not used in the library.

README.md

@@ -52,7 +52,7 @@ others (in my opinion of course):
 * uses the [computed goto](https://gcc.gnu.org/onlinedocs/gcc/Labels-as-Values.html)
   feature of the GCC compiler (also supported by Clang) to avoid the
   [Duff's Device](https://en.wikipedia.org/wiki/Duff%27s_device) hack
-    * allows `switch` statemens in the coroutines
+    * allows `switch` statements in the coroutines
 * C/C++ macros eliminate boilerplate code and make the code easy to read
 * the base `Coroutine` class is easy to subclass to add additional variables and
   functions
@@ -80,7 +80,7 @@ Arduino API (AVR, Teensy, ESP8266, ESP32, etc), and it provides a handful of
 additional macros that can reduce boilerplate code.
 
 
-**Version**: 1.2 (2020-11-10)
+**Version**: 1.2.1 (2020-11-12)
 
 **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 

USER_GUIDE.md

@@ -1,15 +1,15 @@
-# User Guide
+# AceRoutine User Guide
 
 See the [README.md](README.md) for installation instructions and other
 background information. This document describes how to use the library once it
 is installed.
 
-**Version**: 1.2 (2020-11-10)
+**Version**: 1.2.1 (2020-11-12)
 
 **Table of Contents**
 
 * [Coroutine Setup](#Setup)
-    * [Include Header and Namespace](#Include)
+    * [Include Header and Namespace](#IncludeHeader)
     * [Macros](#Macros)
     * [Overall Structure](#OverallStructure)
     * [Coroutine Class](#CoroutineClass)
@@ -26,10 +26,7 @@ is installed.
     * [While Loops](#WhileLoops)
     * [Forever Loops](#ForeverLoops)
     * [Macros As Statements](#MacrosAsStatements)
-* [Coroutine Interactions](#CoroutineInteractions)
-    * [No Nested Loop Macro](#NoNestedLoop)
-    * [No Delegation to Regular Functions](#NoDelegation)
-    * [Chaining Coroutines](#Chaining)
+    * [Chaining Coroutines](#ChainingCoroutines)
 * [Running and Scheduling](#RunningAndScheduling)
     * [Manual Scheduling](#ManualScheduling)
     * [CoroutineScheduler](#CoroutineScheduler)
@@ -38,19 +35,22 @@ is installed.
     * [Reset Coroutine](#Reset)
     * [Coroutine States](#States)
 * [Customizing](#Customizing)
-    * [Custom Coroutines](#Custom)
-    * [Manual Coroutines](#Manual)
+    * [Custom Coroutines](#CustomCoroutines)
+    * [Manual Coroutines](#ManualCoroutines)
 * [Coroutine Communication](#Communication)
     * [Instance Variables](#InstanceVariables)
     * [Channels (Experimental)](#Channels)
 * [Miscellaneous](#Miscellaneous)
     * [External Coroutines](#External)
     * [Functors](#Functors)
+* [Bugs and Limitations](#BugsAndLimitations)
+    * [No Nested LOOP Macro](#NoNestedLoop)
+    * [No Delegation to Regular Functions](#NoDelegation)
 
 <a name="Setup"></a>
 ## Coroutine Setup
 
-<a name="Include"></a>
+<a name="IncludeHeader"></a>
 ### Include Header and Namespace
 
 Only a single header file `AceRoutine.h` is required to use this library.
@@ -191,7 +191,7 @@ subclasses. There are 2 recommended ways of creating coroutines:
 * Manually subclassing the `Coroutine` class.
 
 (The third option is useful mostly for unit testing purposes, and is explained
-later in the [Custom Coroutines](#Custom) section below.)
+later in the [Custom Coroutines](#CustomCoroutines) section below.)
 
 **Using COROUTINE() Macro**
 
@@ -260,7 +260,7 @@ Since we are creating 2 instances of the `MyCoroutine` class, we call the
 the constructor.
 
 For more details on manual Coroutine instances, see the
-[Manual Coroutines](#Manual) section below.
+[Manual Coroutines](#ManualCoroutines) section below.
 
 <a name="CoroutineBody"></a>
 ## Coroutine Body
@@ -622,68 +622,14 @@ example, the following is allowed:
   ...
 ```
 
-<a name="CoroutineInteractions"></a>
-## Coroutine Interactions
-
-Here are some potentially surprising ways that certain macros or Coroutine
-features interact with each other inside the `runCoroutine()` method.
-
-<a name="NoNestedLoop"></a>
-### No Nested Loop Macro
-
-The `COROUTINE_LOOP()` macro cannot be nested. In other words, the following is
-**not** allowed:
-
-```C++
-COROUTINE(routine) {
-  COROUTINE_LOOP() {
-    ...
-    if (condition) {
-      COROUTINE_LOOP() { // <----- NOT ALLOWED
-        ...
-        COROUTINE_YIELD();
-      }
-    }
-    COROUTINE_YIELD();
-  }
-}
-```
-
-<a name="NoDelegation"></a>
-### No Delegation to Regular Functions
-
-Coroutines macros inside the `runCoroutine()` **cannot** be delegated to another
-C/C++ function, even though this becomes tempting when the `runCoroutine()`
-implementation becomes complex. In other words, if you call another function
-from within the `runCoroutine()`, you cannot use the various `COROUTINE_XXX()`
-macros inside the delegated function. The macros were designed to trigger a
-compiler error in most cases, but this is not guaranteed:
-
-```C++
-void doSomething() {
-  ...
-  COROUTINE_YIELD(); // <--- ***compiler error***
-  ...
-}
-
-COROUTINE(cannotUseNestedMacros) {
-  COROUTINE_LOOP() {
-    if (condition) {
-      doSomething(); // <--- doesn't work
-    } else {
-      COROUTINE_YIELD();
-    }
-  }
-}
-```
-
-<a name="Chaining"></a>
+<a name="ChainingCoroutines"></a>
 ### Chaining Coroutines
 
 Coroutines can be chained, in other words, the `runCoroutine()` of one coroutine
 *can* explicitly call the `runCoroutine()` of another coroutine.
 
-I have found it useful to chain coroutines when using the **Manual Coroutines**
+I have found it useful to chain coroutines when using the [Manual
+Coroutines](#ManualCoroutines)
 described in the section below. The ability to chain coroutines allows us to
 implement a [Decorator
 Pattern](https://en.wikipedia.org/wiki/Decorator_pattern), also known as "a
@@ -784,6 +730,7 @@ in the global `loop()` method, like this:
 ```C++
 void setup() {
   ...
+  myRoutine.setupCoroutine(F("myRoutine"));
   CoroutineScheduler::setup();
 }
 
@@ -797,6 +744,11 @@ coroutines that are managed by the scheduler. Each call to
 `CoroutineScheduler::loop()` executes one coroutine in that list in a simple
 round-robin scheduling algorithm.
 
+If you are manually subclassing the `Coroutine` class to create your own
+[Manual Coroutines](#ManualCoroutines), you must call the
+`Coroutine::setupCoroutine()` method in the global `setup()` so that the
+coroutine instance is added to the `CoroutineScheduler`.
+
 Prior to v1.2, the initial ordering was sorted by the `Coroutine::getName()`.
 And calling `suspend()` would remove the coroutine from the internal list
 of coroutines, and `resume()` would add the the coroutine back into the list.
@@ -966,7 +918,7 @@ COROUTINE(doSomethingElse) {
 <a name="Customizing"></a>
 ## Customizing
 
-<a name="Custom"></a>
+<a name="CustomCoroutines"></a>
 ### Custom Coroutines (Not Recommended)
 
 All coroutines are instances of the `Coroutine` class, or one of its subclasses.
@@ -1003,7 +955,7 @@ where I have found this feature to be useful is in writing the
 situation, I suspect that the **Manual Coroutines** section described in
 below will be more useful and easier to understand.
 
-<a name="Manual"></a>
+<a name="ManualCoroutines"></a>
 ### Manual Coroutines (Recommended)
 
 A manual coroutine is a custom coroutine whose body of the coroutine (i.e
@@ -1083,6 +1035,8 @@ Some examples of manual coroutines:
   [BlinkSlowFastRoutine](examples/BlinkSlowFastRoutine)
 * [HelloManualCoroutine](examples/HelloManualCoroutine) which shows the same
   functionality as [HelloCoroutine](examples/HelloCoroutine).
+* [SoundManager](examples/SoundManager) which uses both the automatic coroutine
+  defined by `COROUTINE()` macro and an explicitly subclasses manual coroutine.
 
 <a name="Communication"></a>
 ## Coroutine Communication
@@ -1393,3 +1347,55 @@ C++ allows the creation of objects that look syntactically like functions.
 by defining the `operator()` method on the class. I have not defined this method
 in the `Coroutine` class because I have not found a use-case for it. However, if
 someone can demonstrate a compelling use-case, then I would be happy to add it.
+
+<a name="BugsAndLimitations"></a>
+## Bugs and Limitations
+
+<a name="NoNestedLoop"></a>
+### No Nested LOOP Macro
+
+The `COROUTINE_LOOP()` macro cannot be nested. In other words, the following is
+**not** allowed:
+
+```C++
+COROUTINE(routine) {
+  COROUTINE_LOOP() {
+    ...
+    if (condition) {
+      COROUTINE_LOOP() { // <----- NOT ALLOWED
+        ...
+        COROUTINE_YIELD();
+      }
+    }
+    COROUTINE_YIELD();
+  }
+}
+```
+
+<a name="NoDelegation"></a>
+### No Delegation to Regular Functions
+
+Coroutines macros inside the `runCoroutine()` **cannot** be delegated to another
+C/C++ function, even though this becomes tempting when the `runCoroutine()`
+implementation becomes complex. In other words, if you call another function
+from within the `runCoroutine()`, you cannot use the various `COROUTINE_XXX()`
+macros inside the delegated function. The macros were designed to trigger a
+compiler error in most cases, but this is not guaranteed:
+
+```C++
+void doSomething() {
+  ...
+  COROUTINE_YIELD(); // <--- ***compiler error***
+  ...
+}
+
+COROUTINE(cannotUseNestedMacros) {
+  COROUTINE_LOOP() {
+    if (condition) {
+      doSomething(); // <--- doesn't work
+    } else {
+      COROUTINE_YIELD();
+    }
+  }
+}
+```

docs/doxygen.cfg

@@ -38,7 +38,7 @@ PROJECT_NAME           = "AceRoutine"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 1.2
+PROJECT_NUMBER         = 1.2.1
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

docs/html/AceRoutine_8h_source.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceRoutine
-   &#160;<span id="projectnumber">1.2</span>
+   &#160;<span id="projectnumber">1.2.1</span>
    </div>
    <div id="projectbrief">A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.</div>
   </td>
@@ -103,8 +103,8 @@
 <div class="line"><a name="l00041"></a><span class="lineno">   41</span>&#160;<span class="preprocessor">#include &quot;ace_routine/Channel.h&quot;</span></div>
 <div class="line"><a name="l00042"></a><span class="lineno">   42</span>&#160; </div>
 <div class="line"><a name="l00043"></a><span class="lineno">   43</span>&#160;<span class="comment">// Version format: xxyyzz == &quot;xx.yy.zz&quot;</span></div>
-<div class="line"><a name="l00044"></a><span class="lineno">   44</span>&#160;<span class="preprocessor">#define ACE_ROUTINE_VERSION 10200</span></div>
-<div class="line"><a name="l00045"></a><span class="lineno">   45</span>&#160;<span class="preprocessor">#define ACE_ROUTINE_VERSION_STRING &quot;1.2&quot;</span></div>
+<div class="line"><a name="l00044"></a><span class="lineno">   44</span>&#160;<span class="preprocessor">#define ACE_ROUTINE_VERSION 10201</span></div>
+<div class="line"><a name="l00045"></a><span class="lineno">   45</span>&#160;<span class="preprocessor">#define ACE_ROUTINE_VERSION_STRING &quot;1.2.1&quot;</span></div>
 <div class="line"><a name="l00046"></a><span class="lineno">   46</span>&#160; </div>
 <div class="line"><a name="l00047"></a><span class="lineno">   47</span>&#160;<span class="preprocessor">#endif</span></div>
 </div><!-- fragment --></div><!-- contents -->

docs/html/Channel_8h_source.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceRoutine
-   &#160;<span id="projectnumber">1.2</span>
+   &#160;<span id="projectnumber">1.2.1</span>
    </div>
    <div id="projectbrief">A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.</div>
   </td>

docs/html/CoroutineScheduler_8cpp_source.html

@@ -22,7 +22,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">AceRoutine
-   &#160;<span id="projectnumber">1.2</span>
+   &#160;<span id="projectnumber">1.2.1</span>
    </div>
    <div id="projectbrief">A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.</div>
   </td>