AceRoutine

AceRoutine is a low-memory, fast-switching, cooperative multitasking library for Arduino platforms. It implements stackless coroutines based on the ProtoThreads model, allowing execution to suspend via yield() or delay() and resume later. This allows multiple tasks to appear to run concurrently on microcontrollers with limited resources.

Core Components

• Coroutine: Provides context variables for individual coroutines.
• CoroutineScheduler: Handles the scheduling of multiple coroutines (optional).

Key Features

• Low Memory Footprint: Optimized for both 8-bit (AVR) and 32-bit (ESP32, STM32, etc.) processors.
• Fast Context Switching: Uses GCC/Clang 'computed goto' to avoid Duff's Device hacks, enabling switch statements within coroutines.
• Profiling: Version 1.5+ includes tools to profile Coroutine::runCoroutine() execution time and render results as tables or JSON.
• Experimental Channels: An unbuffered, synchronized Channel class allows one reader and one writer to communicate.

AceRoutine coroutines are stackless. The stack is destroyed and recreated on every invocation. This has critical implications for memory:

1. Local Variables: Standard local variables do not preserve their value across COROUTINE_YIELD(), COROUTINE_DELAY(), or COROUTINE_AWAIT().
2. Local Objects: Using objects with non-trivial destructors (like String) across a yield point will cause the destructor to be called incorrectly upon resumption, likely crashing the program.

Best Practices for State

• Scope Limiting: Wrap local variables/objects in a { } block so they are fully destroyed before a yield point.
• Static Variables: Use static variables inside the COROUTINE() to preserve state across yields. Note that static variables are shared across all instances of that coroutine.
• Class Members: For manual coroutines (subclassing Coroutine), use private member variables to store state. This ensures each instance has its own unique state.

// INCORRECT: String will crash on resumption
COROUTINE(badExample) {
  COROUTINE_BEGIN();
  String s = "hello"; 
  COROUTINE_DELAY(1000);
  COROUTINE_END();
}

// CORRECT: Scope limiting
COROUTINE(goodExample) {
  COROUTINE_BEGIN();
  {
    String s = "hello";
    Serial.println(s);
  } // s is destroyed here
  COROUTINE_DELAY(1000);
  COROUTINE_END();
}

// CORRECT: Using static for state
COROUTINE(statefulExample) {
  COROUTINE_BEGIN();
  static int count = 0;
  count++;
  COROUTINE_DELAY(1000);
  COROUTINE_END();
}

AceRoutine manages coroutines using a singly linked list. When you create a coroutine using the COROUTINE() macro, the instance is automatically inserted into a global linked list. This structure allows the CoroutineScheduler to perform round-robin execution by iterating through the list.

Key Mechanics:

• Automatic Registration: The COROUTINE() macro handles the constructor logic that inserts the new instance into the list.
• The Root Pointer: The list starts at a static root pointer, accessible via the static method Coroutine::getRoot(). This method returns a pointer to the pointer (Coroutine**), which allows for easier manipulation of the list head.
• Scheduler Traversal: The CoroutineScheduler tracks the active coroutine using an mCurrent pointer of type Coroutine**. Using a pointer-to-a-pointer allows the scheduler to:
  • Treat the root node identically to any other node in the list.
  • Insert new nodes immediately after the current node by modifying the mNext pointer of the previous node.
  • Facilitate list traversal and potential node deletion without needing a doubly linked list.

// Concept: Coroutine Linked List Structure
// CoroutineScheduler (mCurrent: Coroutine**) -> Coroutine (mNext: Coroutine*) -> Coroutine (mNext: Coroutine*) -> nullptr

AceRoutine provides a profiling mechanism to measure the execution time of coroutines. It uses a CoroutineProfiler interface to track how long Coroutine::runCoroutine() takes to execute.

When profiling is enabled, you use Coroutine::runCoroutineWithProfiler() (or CoroutineScheduler::loopWithProfiler() when using a scheduler) to measure the elapsed time in microseconds and update the attached profiler.

Resource Impact:

• Static RAM: Increases by 2 bytes (8-bit) or 4 bytes (32-bit) per coroutine regardless of whether profiling is used, due to the internal profiler pointer.
• Flash: Using profiling methods increases flash usage by approximately 50-80 bytes per coroutine due to virtual dispatch.
• CPU Overhead: On 8-bit AVR, expect ~3 microseconds of latency per call. On 32-bit processors (ESP32, STM32), the overhead is negligible (0.1 - 0.4 micros).

class CoroutineProfiler {
  public:
    virtual void updateElapsedMicros(uint32_t micros) = 0;
};

The Channel<T> class provides an unbuffered, bidirectional point of synchronization between coroutines, inspired by Go Lang channels.

Synchronization Behavior:

• The writer blocks (yields) until the reader is ready.
• The reader blocks (yields) until the writer is ready.
• When a writer writes, the reader picks up the message and is allowed to continue execution before the writer is allowed to continue.
• The writer continues execution only after the reader yields.

Limitations:

• Only a single Coroutine can write to a Channel.
• Only a single Coroutine can read from a Channel.
• No select statement (cannot wait for multiple channels simultaneously).
• No buffered channels.
• No way to close a channel.

Usage:

1. Define a message class (often containing a status field).
2. Instantiate Channel<MessageType> channel;.
3. Inject the channel into the constructors of the Writer and Reader coroutines.
4. Use COROUTINE_CHANNEL_WRITE(channel, value) to send data.
5. Use COROUTINE_CHANNEL_READ(channel, value) to receive data.

class Message {
  static uint8_t const kStatusOk = 0;
  static uint8_t const kStatusError = 1;
  uint8_t status;
  int value;
};

Channel<Message> channel;

// In Writer coroutine:
COROUTINE_CHANNEL_WRITE(mChannel, message);

// In Reader coroutine:
COROUTINE_CHANNEL_READ(mChannel, message);