Skip to content

Commit b42183f

Browse files
bxparksbxparks
authored
Merge pull request #37 from bxparks/develop
merge 1.4.0 into master
2 parents 256dfc3 + 44d3391 commit b42183f

File tree

79 files changed

+1469
-938
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

79 files changed

+1469
-938
lines changed

‎CHANGELOG.md‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,27 @@
11
# Changelog
22

33
* Unreleased
4+
* 1.4.0 (2021-07-29)
5+
* Upgrade STM32duino Core from 1.9.0 to 2.0.0.
6+
* MemoryBenchmark: Flash usage increases by 2.3kB across the board, but
7+
static RAM goes down by 250 bytes. Very little change to AceRoutine
8+
code itself.
9+
* AutoBenchmark: No change.
10+
* Upgrade SparkFun SAMD Core from 1.8.1 to 1.8.3.
11+
* No change observed in MemoryBenchmark or AutoBenchmark.
12+
* Add virtual `Coroutine::setupCoroutine()` with a default empty
13+
implementation, and optional `CoroutineScheduler::setupCoroutines()` to
14+
automatically loop over all coroutines.
15+
* See [Issue #36](https://github.com/bxparks/AceRoutine/issues/36) for
16+
motivation.
17+
* If not used, `Coroutine::setupCoroutine()` increases flash consumption
18+
by 4 bytes, and static memory by 2 bytes per coroutine on AVR
19+
processors.
20+
* If used, `Coroutine::setupCoroutine()` can consume a significant
21+
amount of memory resources. On AVR, at least 50-60 bytes per
22+
coroutine. On 32-bit processors, about 30-40 bytes per coroutine.
423
* 1.3.1 (2021-06-02)
5-
* Bring back `COROUTINE_DELAY_MICROS()` and `COROUTINE_DELAY_SECONDS(),
24+
* Bring back `COROUTINE_DELAY_MICROS()` and `COROUTINE_DELAY_SECONDS()`
625
with an alternate implemenation that increases flash and static memory
726
*only* if they are used.
827
* The `Coroutine` itself knows whether it is delaying in units of
@@ -11,7 +30,7 @@
1130
* Make `CoroutineScheduler::runCoroutine()` always call into
1231
`Coroutine::runCoroutine()` when the `Coroutine::mStatus` is delaying,
1332
instead of preemptively trying to figure out if the delay has expired.
14-
* `Coroutine` does not need a runtime `mDelayType` descriminator.
33+
* `Coroutine` no longer needs a runtime `mDelayType` descriminator.
1534
* The result is that the code to support `COROUTINE_DELAY_MICROS()` and
1635
`COROUTINE_DELAY_SECONDS()` is not pulled into the program if they are
1736
not used.

‎README.md‎

Lines changed: 74 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,6 @@
22

33
[![AUnit Tests](https://github.com/bxparks/AceRoutine/actions/workflows/aunit_tests.yml/badge.svg)](https://github.com/bxparks/AceRoutine/actions/workflows/aunit_tests.yml)
44

5-
**New**: [GitHub Discussions](https://github.com/bxparks/AceRoutine/discussions)
6-
for this project is now active! Let's use that for general support questions,
7-
and reserve the [GitHub Issues](https://github.com/bxparks/AceRoutine/issues)
8-
section for bugs and feature requests.
9-
105
**Breaking Changes in v1.3**: Breaking changes were made in v1.3 to reduce the
116
flash memory consumption of `Coroutine` instances by 800-1000 bytes. See the
127
[CHANGELOG.md](CHANGELOG.md) for a complete list.
@@ -57,8 +52,7 @@ others (in my opinion of course):
5752
* `CoroutineScheduler` consumes only about 40 bytes of flash and
5853
2 bytes of RAM independent of the number of coroutines
5954
* 32-bit (e.g. STM32, ESP8266, ESP32) processors
60-
* the first `Coroutine` consumes between 120-450 bytes of flash (except
61-
on the Teensy 3.2 where the first instance brings in 3200 bytes)
55+
* the first `Coroutine` consumes between 120-450 bytes of flash
6256
* each additional `Coroutine` consumes about 130-160 bytes of flash,
6357
* each `Coroutine` consumes 20 bytes of static RAM
6458
* `CoroutineScheduler` consumes only about 40-60 bytes of flash
@@ -110,7 +104,7 @@ AceRoutine is a self-contained library that works on any platform supporting the
110104
Arduino API (AVR, Teensy, ESP8266, ESP32, etc), and it provides a handful of
111105
additional macros that can reduce boilerplate code.
112106

113-
**Version**: 1.3.1 (2021-06-02)
107+
**Version**: 1.4.0 (2021-07-29)
114108

115109
**Changelog**: [CHANGELOG.md](CHANGELOG.md)
116110

@@ -505,69 +499,81 @@ etc) for a handful of AceRoutine features. Here are some highlights:
505499
**Arduino Nano (8-bits)**
506500
507501
```
508-
+------------------------------------------------------------------+
509-
| functionality | flash/ ram | delta |
510-
|-------------------------------------+--------------+-------------|
511-
| Baseline | 400/ 11 | 0/ 0 |
512-
|-------------------------------------+--------------+-------------|
513-
| One Delay Function | 450/ 13 | 50/ 2 |
514-
| Two Delay Functions | 508/ 15 | 108/ 4 |
515-
|-------------------------------------+--------------+-------------|
516-
| One Coroutine | 628/ 30 | 228/ 19 |
517-
| Two Coroutines | 796/ 47 | 396/ 36 |
518-
|-------------------------------------+--------------+-------------|
519-
| One Coroutine (micros) | 596/ 30 | 196/ 19 |
520-
| Two Coroutines (micros) | 732/ 47 | 332/ 36 |
521-
|-------------------------------------+--------------+-------------|
522-
| One Coroutine (seconds) | 724/ 30 | 324/ 19 |
523-
| Two Coroutines (seconds) | 920/ 47 | 520/ 36 |
524-
|-------------------------------------+--------------+-------------|
525-
| Scheduler, One Coroutine | 742/ 32 | 342/ 21 |
526-
| Scheduler, Two Coroutines | 904/ 49 | 504/ 38 |
527-
|-------------------------------------+--------------+-------------|
528-
| Scheduler, One Coroutine (micros) | 710/ 32 | 310/ 21 |
529-
| Scheduler, Two Coroutines (micros) | 840/ 49 | 440/ 38 |
530-
|-------------------------------------+--------------+-------------|
531-
| Scheduler, One Coroutine (seconds) | 838/ 32 | 438/ 21 |
532-
| Scheduler, Two Coroutines (seconds) | 1028/ 49 | 628/ 38 |
533-
|-------------------------------------+--------------+-------------|
534-
| Blink Function | 546/ 14 | 146/ 3 |
535-
| Blink Coroutine | 752/ 30 | 352/ 19 |
536-
+------------------------------------------------------------------+
502+
+--------------------------------------------------------------------+
503+
| functionality | flash/ ram | delta |
504+
|---------------------------------------+--------------+-------------|
505+
| Baseline | 606/ 11 | 0/ 0 |
506+
|---------------------------------------+--------------+-------------|
507+
| One Delay Function | 654/ 13 | 48/ 2 |
508+
| Two Delay Functions | 714/ 15 | 108/ 4 |
509+
|---------------------------------------+--------------+-------------|
510+
| One Coroutine | 844/ 32 | 238/ 21 |
511+
| Two Coroutines | 1016/ 51 | 410/ 40 |
512+
|---------------------------------------+--------------+-------------|
513+
| One Coroutine (micros) | 816/ 32 | 210/ 21 |
514+
| Two Coroutines (micros) | 960/ 51 | 354/ 40 |
515+
|---------------------------------------+--------------+-------------|
516+
| One Coroutine (seconds) | 944/ 32 | 338/ 21 |
517+
| Two Coroutines (seconds) | 1148/ 51 | 542/ 40 |
518+
|---------------------------------------+--------------+-------------|
519+
| Scheduler, One Coroutine | 968/ 34 | 362/ 23 |
520+
| Scheduler, Two Coroutines | 1132/ 53 | 526/ 42 |
521+
|---------------------------------------+--------------+-------------|
522+
| Scheduler, One Coroutine (micros) | 940/ 34 | 334/ 23 |
523+
| Scheduler, Two Coroutines (micros) | 1076/ 53 | 470/ 42 |
524+
|---------------------------------------+--------------+-------------|
525+
| Scheduler, One Coroutine (seconds) | 1068/ 34 | 462/ 23 |
526+
| Scheduler, Two Coroutines (seconds) | 1264/ 53 | 658/ 42 |
527+
|---------------------------------------+--------------+-------------|
528+
| Scheduler, One Coroutine (setup) | 1018/ 34 | 412/ 23 |
529+
| Scheduler, Two Coroutines (setup) | 1282/ 53 | 676/ 42 |
530+
|---------------------------------------+--------------+-------------|
531+
| Scheduler, One Coroutine (man setup) | 996/ 34 | 390/ 23 |
532+
| Scheduler, Two Coroutines (man setup) | 1268/ 53 | 662/ 42 |
533+
|---------------------------------------+--------------+-------------|
534+
| Blink Function | 938/ 14 | 332/ 3 |
535+
| Blink Coroutine | 1158/ 32 | 552/ 21 |
536+
+--------------------------------------------------------------------+
537537
```
538538
539539
**ESP8266 (32-bits)**
540540
541541
```
542-
+------------------------------------------------------------------+
543-
| functionality | flash/ ram | delta |
544-
|-------------------------------------+--------------+-------------|
545-
| Baseline | 256924/26800 | 0/ 0 |
546-
|-------------------------------------+--------------+-------------|
547-
| One Delay Function | 256988/26808 | 64/ 8 |
548-
| Two Delay Functions | 257052/26808 | 128/ 8 |
549-
|-------------------------------------+--------------+-------------|
550-
| One Coroutine | 257104/26820 | 180/ 20 |
551-
| Two Coroutines | 257264/26844 | 340/ 44 |
552-
|-------------------------------------+--------------+-------------|
553-
| One Coroutine (micros) | 257136/26820 | 212/ 20 |
554-
| Two Coroutines (micros) | 257296/26844 | 372/ 44 |
555-
|-------------------------------------+--------------+-------------|
556-
| One Coroutine (seconds) | 257136/26820 | 212/ 20 |
557-
| Two Coroutines (seconds) | 257312/26844 | 388/ 44 |
558-
|-------------------------------------+--------------+-------------|
559-
| Scheduler, One Coroutine | 257152/26828 | 228/ 28 |
560-
| Scheduler, Two Coroutines | 257280/26844 | 356/ 44 |
561-
|-------------------------------------+--------------+-------------|
562-
| Scheduler, One Coroutine (micros) | 257168/26828 | 244/ 28 |
563-
| Scheduler, Two Coroutines (micros) | 257312/26844 | 388/ 44 |
564-
|-------------------------------------+--------------+-------------|
565-
| Scheduler, One Coroutine (seconds) | 257168/26828 | 244/ 28 |
566-
| Scheduler, Two Coroutines (seconds) | 257328/26844 | 404/ 44 |
567-
|-------------------------------------+--------------+-------------|
568-
| Blink Function | 257424/26816 | 500/ 16 |
569-
| Blink Coroutine | 257556/26836 | 632/ 36 |
570-
+------------------------------------------------------------------+
542+
+--------------------------------------------------------------------+
543+
| functionality | flash/ ram | delta |
544+
|---------------------------------------+--------------+-------------|
545+
| Baseline | 256924/26800 | 0/ 0 |
546+
|---------------------------------------+--------------+-------------|
547+
| One Delay Function | 256988/26808 | 64/ 8 |
548+
| Two Delay Functions | 257052/26808 | 128/ 8 |
549+
|---------------------------------------+--------------+-------------|
550+
| One Coroutine | 257120/26820 | 196/ 20 |
551+
| Two Coroutines | 257280/26844 | 356/ 44 |
552+
|---------------------------------------+--------------+-------------|
553+
| One Coroutine (micros) | 257136/26820 | 212/ 20 |
554+
| Two Coroutines (micros) | 257296/26844 | 372/ 44 |
555+
|---------------------------------------+--------------+-------------|
556+
| One Coroutine (seconds) | 257136/26820 | 212/ 20 |
557+
| Two Coroutines (seconds) | 257312/26844 | 388/ 44 |
558+
|---------------------------------------+--------------+-------------|
559+
| Scheduler, One Coroutine | 257168/26828 | 244/ 28 |
560+
| Scheduler, Two Coroutines | 257312/26844 | 388/ 44 |
561+
|---------------------------------------+--------------+-------------|
562+
| Scheduler, One Coroutine (micros) | 257184/26828 | 260/ 28 |
563+
| Scheduler, Two Coroutines (micros) | 257328/26844 | 404/ 44 |
564+
|---------------------------------------+--------------+-------------|
565+
| Scheduler, One Coroutine (seconds) | 257184/26828 | 260/ 28 |
566+
| Scheduler, Two Coroutines (seconds) | 257344/26844 | 420/ 44 |
567+
|---------------------------------------+--------------+-------------|
568+
| Scheduler, One Coroutine (setup) | 257200/26828 | 276/ 28 |
569+
| Scheduler, Two Coroutines (setup) | 257376/26844 | 452/ 44 |
570+
|---------------------------------------+--------------+-------------|
571+
| Scheduler, One Coroutine (man setup) | 257184/26828 | 260/ 28 |
572+
| Scheduler, Two Coroutines (man setup) | 257360/26844 | 436/ 44 |
573+
|---------------------------------------+--------------+-------------|
574+
| Blink Function | 257424/26816 | 500/ 16 |
575+
| Blink Coroutine | 257572/26836 | 648/ 36 |
576+
+--------------------------------------------------------------------+
571577
```
572578
573579
Comparing `Blink Function` and `Blink Coroutine` is probably the most
@@ -653,8 +659,8 @@ This library was developed and tested using:
653659
* [Arduino AVR Boards 1.8.3](https://github.com/arduino/ArduinoCore-avr)
654660
* [Arduino SAMD Boards 1.8.9](https://github.com/arduino/ArduinoCore-samd)
655661
* [SparkFun AVR Boards 1.1.13](https://github.com/sparkfun/Arduino_Boards)
656-
* [SparkFun SAMD Boards 1.8.1](https://github.com/sparkfun/Arduino_Boards)
657-
* [STM32duino 1.9.0](https://github.com/stm32duino/Arduino_Core_STM32)
662+
* [SparkFun SAMD Boards 1.8.3](https://github.com/sparkfun/Arduino_Boards)
663+
* [STM32duino 2.0.0](https://github.com/stm32duino/Arduino_Core_STM32)
658664
* [ESP8266 Arduino 2.7.4](https://github.com/esp8266/Arduino)
659665
* [ESP32 Arduino 1.0.6](https://github.com/espressif/arduino-esp32)
660666
* [Teensydino 1.53](https://www.pjrc.com/teensy/td_download.html)

‎USER_GUIDE.md‎

Lines changed: 80 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ See the [README.md](README.md) for installation instructions and other
44
background information. This document describes how to use the library once it
55
is installed.
66

7-
**Version**: 1.3.1 (2021-06-02)
7+
**Version**: 1.4.0 (2021-07-29)
88

99
## Table of Contents
1010

@@ -37,6 +37,7 @@ is installed.
3737
* [Customizing](#Customizing)
3838
* [Custom Coroutines](#CustomCoroutines)
3939
* [Manual Coroutines](#ManualCoroutines)
40+
* [Coroutine Setup](#CoroutineSetup)
4041
* [Coroutine Communication](#Communication)
4142
* [Instance Variables](#InstanceVariables)
4243
* [Channels (Experimental)](#Channels)
@@ -149,6 +150,8 @@ class Coroutine {
149150
public:
150151
virtual int runCoroutine() = 0;
151152
153+
virtual void setupCoroutine() {}
154+
152155
void suspend();
153156
154157
void resume();
@@ -997,7 +1000,6 @@ class ManualCoroutine : public Coroutine {
9971000
...
9981001
}
9991002

1000-
private:
10011003
int runCoroutine() override {
10021004
COROUTINE_BEGIN();
10031005
// insert coroutine code here
@@ -1025,6 +1027,80 @@ Some examples of manual coroutines:
10251027
* [SoundManager](examples/SoundManager) which uses both the automatic coroutine
10261028
defined by `COROUTINE()` macro and an explicitly subclasses manual coroutine.
10271029
1030+
<a name="CoroutineSetup"></a>
1031+
### Coroutine Setup
1032+
1033+
When creating custom subclasses through the Manual Coroutine workflow (see
1034+
above), you have the ability to override the `setupCoroutine()` method if you
1035+
need to:
1036+
1037+
```C++
1038+
class ManualCoroutine : public Coroutine {
1039+
public:
1040+
// Inject external dependencies into the constructor.
1041+
ManualCoroutine(Params, ..., Objects, ...) {
1042+
...
1043+
}
1044+
1045+
int runCoroutine() override {
1046+
COROUTINE_BEGIN();
1047+
// insert coroutine code here
1048+
COROUTINE_END();
1049+
}
1050+
1051+
void setupCoroutine() override {
1052+
...
1053+
}
1054+
};
1055+
```
1056+
1057+
If you have only a few coroutines that need to override the `setupCoroutine()`,
1058+
it is probably easiest to just call it directly from the global `setup()`:
1059+
1060+
```C++
1061+
ManualCoroutine1 coroutine1;
1062+
ManualCoroutine2 coroutine2;
1063+
1064+
void setup() {
1065+
coroutine1.setupCoroutine();
1066+
coroutine2.setupCoroutine();
1067+
1068+
CoroutineScheduler::setup();
1069+
...
1070+
}
1071+
```
1072+
1073+
If you have significant number of coroutines, or if you have enough flash and
1074+
static memory that you don't need to worry about memory consumption, then you
1075+
can call the `CoroutineScheduler::setupCoroutines()`. It will loop through the
1076+
list of coroutines, and call the `setupCoroutine()` method of each coroutine
1077+
automatically:
1078+
1079+
```C++
1080+
ManualCoroutine1 coroutine1;
1081+
ManualCoroutine2 coroutine2;
1082+
1083+
void setup() {
1084+
CoroutineScheduler::setupCoroutines();
1085+
1086+
CoroutineScheduler::setup();
1087+
...
1088+
}
1089+
```
1090+
1091+
You need to call `CoroutineScheduler::setupCoroutines()` explicitly if you want
1092+
it. The `CoroutineScheduler::setup()` method does *not* call `setupCoroutines()`
1093+
automatically.
1094+
1095+
**Warning**: The `Coroutine::setupCoroutine()` can consume significant amounts
1096+
of memory, especially on AVR processors. On AVR processors, each
1097+
`setupCoroutine()` overridden in the subclass consumes at least 50-60 bytes of
1098+
flash per coroutine. On 32-bit processors, it takes slightly less memory, about
1099+
30-40 bytes per coroutine. The looping code in
1100+
`CoroutineScheduler::setupCoroutines()` consumes about 20-30 bytes of flash on
1101+
AVR processors. The virtual dispatch on `Coroutine::setupCoroutine()` consumes
1102+
about 14 bytes of flash per invocation.
1103+
10281104
<a name="Communication"></a>
10291105
## Coroutine Communication
10301106

@@ -1288,14 +1364,14 @@ void blink() {
12881364
12891365
if (blinkState == kBlinkStateHigh) {
12901366
uint16_t nowMillis = millis();
1291-
if (nowMillis - prevMillis >= 100) {
1367+
if ((uint16_t) (nowMillis - prevMillis) >= 100) {
12921368
prevMillis = nowMillis;
12931369
digitalWrite(LED_BUILTIN, LOW);
12941370
blinkState = kBlinkStateLow;
12951371
}
12961372
} else {
12971373
uint16_t nowMillis = millis();
1298-
if (nowMillis - prevMillis >= 500) {
1374+
if ((uint16_t) (nowMillis - prevMillis) >= 500) {
12991375
prevMillis = nowMillis;
13001376
digitalWrite(LED_BUILTIN, HIGH);
13011377
blinkState = kBlinkStateHigh;

‎docs/doxygen.cfg‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ PROJECT_NAME = "AceRoutine"
3838
# could be handy for archiving the generated documentation or if some version
3939
# control system is used.
4040

41-
PROJECT_NUMBER = 1.3.1
41+
PROJECT_NUMBER = 1.4.0
4242

4343
# Using the PROJECT_BRIEF tag one can provide an optional one line description
4444
# for a project that appears at the top of each page and should give viewer a

0 commit comments

Comments
 (0)