Merge pull request #17 from bxparks/develop

merge 1.1 into master

Author: bxparks

.github/workflows/aunit_tests.yml

@@ -14,6 +14,7 @@ jobs:
       run: |
         cd ..
         git clone https://github.com/bxparks/UnixHostDuino
+        git clone https://github.com/bxparks/AceCommon
         git clone https://github.com/bxparks/AUnit
 
     - name: Verify examples

CHANGELOG.md

@@ -1,6 +1,20 @@
 # Changelog
 
 * Unreleased
+* 1.1 (2020-11-01)
+    * Add a `Coroutine::reset()` method that causes the Coroutine to restart
+      from the beginning of the coroutine upon the next iteration. (Fixes #13
+      and #14).
+    * **Potentially Breaking**: AceRoutine now depends on the AceCommon
+      (https://github.com/bxparks/AceCommon) library to avoid maintaining
+      multiple versions of low-level common code. The externally exposed API has
+      not changed. The AceCommon library can be installed through the Arduino
+      IDE Library Manager, as explained in Installation section of the
+      README.md.
+    * **Potentially Breaking**: Move the CommandLineInterface package from
+      `src/ace_routine/cli` to the AceUtils library
+      (https://github.com/bxparks/AceUtils). The AceUtils library is a better
+      home for this higher-level package that depends on AceRoutine.
 * 1.0.1 (2020-09-18)
     * Add continuous integration using GitHub Actions.
     * Add more documentation and examples of Manual Coroutines in README.md.

README.md

@@ -80,9 +80,9 @@ Arduino API (AVR, Teensy, ESP8266, ESP32, etc), and it provides a handful of
 additional macros that can reduce boilerplate code.
 
 
-**Version**: 1.0.1 (2020-09-18)
+**Version**: 1.1 (2020-11-01)
 
-**Changelog**: [CHANGELOG.md](CHANGELOG.md).
+**Changelog**: [CHANGELOG.md](CHANGELOG.md)
 
 ![AUnit Tests](https://github.com/bxparks/AceRoutine/workflows/AUnit%20Tests/badge.svg)
 
@@ -231,21 +231,30 @@ void loop() {
 
 ## Installation
 
-The latest stable release is available in the Arduino IDE Library Manager.
-Search for "AceRoutine". Click Install.
+The latest stable release is available in the Arduino IDE Library Manager. Two
+libraries need to be installed since v1.1:
 
-The development version can be installed by cloning the
-[GitHub repository](https://github.com/bxparks/AceRoutine), checking out the
-`develop` branch, then manually copying over the contents to the `./libraries`
-directory used by the Arduino IDE. (The result is a directory named
-`./libraries/AceRoutine`.) The `master` branch contains the stable release.
+* Search for "AceRoutine". Click Install.
+* Search for "AceCommon". Click Install.
+
+The development version can be installed by cloning the 2 git repos:
+
+* AceRoutine (https://github.com/bxparks/AceRoutine)
+* AceCommon  (https://github.com/bxparks/AceCommon)
+
+You can copy these directories to the `./libraries` directory used by the
+Arduino IDE. (The result is a directory named `./libraries/AceRoutine` and
+`./libraries/AceCommon`). Or you can create symlinks from `/.libraries` to these
+directories.
+
+The `develop` branch contains the latest working version.
+The `master` branch contains the stable release.
 
 ### Source Code
 
 The source files are organized as follows:
 * `src/AceRoutine.h` - main header file
 * `src/ace_routine/` - implementation files
-* `src/ace_routine/cli` - command line interface library
 * `src/ace_routine/testing/` - internal testing files
 * `tests/` - unit tests which depend on
   [AUnit](https://github.com/bxparks/AUnit)
@@ -274,12 +283,6 @@ The following example sketches are provided:
 * [BlinkSlowFastManualRoutine.ino](examples/BlinkSlowFastManualRoutine): same
   as BlinkSlowFastRoutine but using manual `Coroutine` subclasses
 * [CountAndBlink.ino](examples/CountAndBlink): count and blink at the same time
-* [CommandLineShell.ino](examples/CommandLineShell): uses the
-  `src/ace_routine/cli` classes to implement a command line interface that
-  accepts a number of commands on the serial port. In other words, it is a
-  primitive "shell". The shell is non-blocking and uses coroutines so that other
-  coroutines continue to run while the board waits for commands to be typed on
-  the serial port.
 * [Delay.ino](examples/Delay): validate the various delay macros
   (`COROUTINE_DELAY()`, `COROUTINE_DELAY_MICROS()` and
   `COROUTINE_DELAY_SECONDS()`)
@@ -366,6 +369,51 @@ void loop() {
 }
 ```
 
+### Coroutine Class
+
+The `Coroutine` class looks something like this (not all public methods shown):
+
+```C++
+class Coroutine {
+  public:
+    static Coroutine** getRoot();
+
+    const ace_common::FCString& getName() const;
+
+    virtual int runCoroutine() = 0;
+
+    virtual unsigned long coroutineMillis() const;
+
+    virtual unsigned long coroutineMicros() const;
+
+    virtual unsigned long coroutineSeconds() const;
+
+    void suspend();
+
+    void resume();
+
+    void reset();
+
+    bool isSuspended() const;
+
+    bool isYielding() const;
+
+    bool isDelaying() const;
+
+    bool isRunning() const;
+
+    bool isEnding() const;
+
+    bool isTerminated() const;
+
+    bool isDone() const;
+
+    void setupCoroutine(const char* name);
+
+    void setupCoroutine(const __FlashStringHelper* name);
+};
+```
+
 ### Coroutine Instance
 
 All coroutines are instances of the `Coroutine` class or one of its
@@ -383,6 +431,25 @@ subclass of `Coroutine`. The name of this subclass is autogenerated to be
 `Coroutine_doSomething` but it is unlikely that you will need know the exact
 name of this generated class.
 
+If you expand the `COROUTINE()` macro from `Coroutine.h`, the above code is
+equivalent to writing out the following by hand:
+
+```C++
+struct Coroutine_doSomething: Coroutine {
+  Coroutine_doSomething() {
+    setupCoroutine(F("doSomething"));
+  }
+
+  int runCoroutine() override {
+    COROUTINE_BEGIN();
+    ...
+    COROUTINE_END();
+  }
+};
+
+Coroutine_doSomething doSomething;
+```
+
 ### Coroutine Body
 
 The code immediately following the `COROUTINE()` macro becomes the body of the
@@ -862,6 +929,23 @@ If the `Coroutine::suspend()` method is called on the coroutine *before*
 coroutine into the active list of coroutines at all. This is useful in unit
 tests to prevent extraneous coroutines from interfering with test validation.
 
+### Reset Coroutine
+
+A coroutine can be reset to its initial state using the `Coroutine::reset()`
+method so that the next time `runCoroutine()` is called, it begins execution
+from the start of that method instead of the most recent continuation point
+(i.e. after a `COROUTINE_YIELD()`, `COROUTINE_DELAY()`, etc).
+
+If the coroutine object has any other state variables, for example, additional
+member variables of the Coroutine subclass, or static variables inside the
+`runCoroutine()` method, you may ned to manually reset those variables to their
+initial states as well.
+
+Personally, I have never needed the `reset()` functionalty, but it is apparently
+useful for some people. See for example
+[Issue #13](https://github.com/bxparks/AceRoutine/issues/13) and
+[Issue #14](https://github.com/bxparks/AceRoutine/issues/14).
+
 ### Coroutine States
 
 A coroutine has several internal states:
@@ -1332,14 +1416,12 @@ void loop() {
 
 **Examples**
 
-A really good example of using a `Channel` can be found in the
-[ace_routine/cli](src/ace_routine/cli) package which uses 2 coroutines
-and a channel between them to communicate:
-
-* `StreamLineReader.h`: a coroutine that reads from `Serial` and writes to a
-  `Channel`
-* `CommandDispatcher.h`: a coroutine that reads from a `Channel` and dispatches
-  to a `CommandHandler`
+The CommandLineInterface package in the AceUtils library
+(https://github.com/bxparks/AceUtils) uses 2 Coroutines which communicate with
+each other using a Channel. One coroutine reads from the `Serial` port, while
+the other coroutine writes the output of the command to the `Serial` port.
+Neither coroutines are blocking, which allows other coroutines to do other
+things.
 
 **Limitations**
 

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.0.1
+PROJECT_NUMBER         = 1.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
@@ -2156,15 +2156,15 @@ ENABLE_PREPROCESSING   = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
 # the macro expansion is limited to the macros specified with the PREDEFINED and
 # EXPAND_AS_DEFINED tags.
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_ONLY_PREDEF     = NO
+EXPAND_ONLY_PREDEF     = YES
 
 # If the SEARCH_INCLUDES tag is set to YES, the include files in the
 # INCLUDE_PATH will be searched if a #include is found.
@@ -2196,7 +2196,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             =
+PREDEFINED             = PROGMEM=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

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.0.1</span>
+   &#160;<span id="projectnumber">1.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="l00037"></a><span class="lineno">   37</span>&#160;<span class="preprocessor">#include &quot;ace_routine/Channel.h&quot;</span></div>
 <div class="line"><a name="l00038"></a><span class="lineno">   38</span>&#160; </div>
 <div class="line"><a name="l00039"></a><span class="lineno">   39</span>&#160;<span class="comment">// Version format: xxyyzz == &quot;xx.yy.zz&quot;</span></div>
-<div class="line"><a name="l00040"></a><span class="lineno">   40</span>&#160;<span class="preprocessor">#define ACE_ROUTINE_VERSION 10001</span></div>
-<div class="line"><a name="l00041"></a><span class="lineno">   41</span>&#160;<span class="preprocessor">#define ACE_ROUTINE_VERSION_STRING &quot;1.0.1&quot;</span></div>
+<div class="line"><a name="l00040"></a><span class="lineno">   40</span>&#160;<span class="preprocessor">#define ACE_ROUTINE_VERSION 10100</span></div>
+<div class="line"><a name="l00041"></a><span class="lineno">   41</span>&#160;<span class="preprocessor">#define ACE_ROUTINE_VERSION_STRING &quot;1.1&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="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.0.1</span>
+   &#160;<span id="projectnumber">1.1</span>
    </div>
    <div id="projectbrief">A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.</div>
   </td>