AceRoutine
1.0
A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.
|
A coroutine that reads lines from the Serial port, tokenizes the line on whitespace boundaries, and calls the appropriate command handler to handle the command. More...
#include <CommandDispatcher.h>
Public Member Functions | |
CommandDispatcher (Channel< InputLine > &channel, Print &printer, const CommandHandler *const *commands, uint8_t numCommands, const char **argv, uint8_t argvSize, const char *prompt) | |
Constructor. More... | |
virtual | ~CommandDispatcher () |
Destructor. More... | |
int | runCoroutine () override |
The body of the coroutine. More... | |
const CommandHandler * | findCommand (const char *cmd) const |
Find the CommandHandler of the given command name. More... | |
![]() | |
Coroutine ** | getNext () |
Return the next pointer as a pointer to the pointer, similar to getRoot(). More... | |
const FCString & | getName () const |
Human-readable name of the coroutine. More... | |
virtual unsigned long | coroutineMillis () const |
Returns the current millisecond clock. More... | |
virtual unsigned long | coroutineMicros () const |
Returns the current millisecond clock. More... | |
virtual unsigned long | coroutineSeconds () const |
Returns the current clock in unit of seconds, truncated to the lower 16-bits. More... | |
void | suspend () |
Suspend the coroutine at the next scheduler iteration. More... | |
void | resume () |
Add a Suspended coroutine into the head of the scheduler linked list, and change the state to Yielding. More... | |
bool | isDelayExpired () |
Check if delay time is over. More... | |
bool | isSuspended () const |
The coroutine was suspended with a call to suspend(). More... | |
bool | isYielding () const |
The coroutine returned using COROUTINE_YIELD(). More... | |
bool | isDelaying () const |
The coroutine returned using COROUTINE_DELAY(). More... | |
bool | isRunning () const |
The coroutine is currently running. More... | |
bool | isEnding () const |
The coroutine returned using COROUTINE_END(). More... | |
bool | isTerminated () const |
The coroutine was terminated by the scheduler with a call to setTerminated(). More... | |
bool | isDone () const |
The coroutine is either Ending or Terminated. More... | |
void | setupCoroutine (const char *name) |
Initialize the coroutine for the CoroutineScheduler, set it to Yielding state, and add it to the linked list of coroutines. More... | |
void | setupCoroutine (const __FlashStringHelper *name) |
Same as setupCoroutine(const char*) except using flash string type. More... | |
Static Public Member Functions | |
static uint8_t | tokenize (char *line, const char **argv, uint8_t argvSize) |
Tokenize the line, separating tokens delimited by whitespace (space, formfeed, carriage return, newline, tab, and vertical tab) and fill argv with each token until argvSize is reached. More... | |
![]() | |
static Coroutine ** | getRoot () |
Get the pointer to the root pointer. More... | |
Protected Member Functions | |
CommandDispatcher (const CommandDispatcher &)=delete | |
CommandDispatcher & | operator= (const CommandDispatcher &)=delete |
void | printLineError (const char *line, uint8_t statusCode) const |
Print the input line that caused an error along with its status code. More... | |
void | helpCommandHandler (Print &printer, int argc, const char *const *argv) const |
Handle the 'help' command. More... | |
void | helpAll (Print &printer) const |
Print help on all commands. | |
bool | helpSpecific (Print &printer, const char *cmd) const |
Print helpString of specific cmd. More... | |
void | runCommand (char *line) const |
Tokenize the given line and run the command handler. More... | |
void | findAndRunCommand (const char *cmd, int argc, const char *const *argv) const |
Find and run the given command. More... | |
![]() | |
Coroutine () | |
Constructor. More... | |
virtual | ~Coroutine () |
Destructor. More... | |
Status | getStatus () const |
Return the status of the coroutine. More... | |
void | statusPrintTo (Print &printer) |
Print the human-readable string of the Status. More... | |
void | setJump (void *jumpPoint) |
Pointer to label where execute will start on the next call to runCoroutine(). | |
void * | getJump () const |
Pointer to label where execute will start on the next call to runCoroutine(). | |
void | setRunning () |
Set the kStatusRunning state. More... | |
void | setYielding () |
Set the kStatusDelaying state. More... | |
void | setDelaying () |
Set the kStatusDelaying state. More... | |
void | setEnding () |
Set the kStatusEnding state. More... | |
void | setTerminated () |
Set status to indicate that the Coroutine has been removed from the Scheduler queue. More... | |
void | setDelayMillis (uint16_t delayMillis) |
Configure the delay timer for delayMillis. More... | |
void | setDelayMicros (uint16_t delayMicros) |
Configure the delay timer for delayMicros. More... | |
void | setDelaySeconds (uint16_t delaySeconds) |
Configure the delay timer for delaySeconds. More... | |
Static Protected Member Functions | |
static void | printHelp (Print &printer, const CommandHandler *command) |
Print help string for the given command. More... | |
Protected Attributes | |
Channel< InputLine > & | mChannel |
Print & | mPrinter |
const CommandHandler *const *const | mCommands |
uint8_t const | mNumCommands |
const char **const | mArgv |
uint8_t const | mArgvSize |
const char *const | mPrompt |
Static Protected Attributes | |
static const uint8_t | STATUS_SUCCESS = 0 |
static const uint8_t | STATUS_BUFFER_OVERFLOW = 1 |
static const uint8_t | STATUS_FLUSH_TO_EOL = 2 |
static const char | DELIMS [] = " \f\r\n\t\v" |
![]() | |
static const Status | kStatusSuspended = 0 |
Coroutine has been suspended using suspend() and the scheduler should remove it from the queue upon the next iteration. More... | |
static const Status | kStatusYielding = 1 |
Coroutine returned using the COROUTINE_YIELD() statement. More... | |
static const Status | kStatusDelaying = 2 |
Coroutine returned using the COROUTINE_DELAY() statement. More... | |
static const Status | kStatusRunning = 3 |
Coroutine is currenly running. More... | |
static const Status | kStatusEnding = 4 |
Coroutine executed the COROUTINE_END() statement. More... | |
static const Status | kStatusTerminated = 5 |
Coroutine has ended and no longer in the scheduler queue. More... | |
static const uint8_t | kDelayTypeMillis = 0 |
Delay using units of millis. More... | |
static const uint8_t | kDelayTypeMicros = 1 |
Delay using units of micros. More... | |
static const uint8_t | kDelayTypeSeconds = 2 |
Delay using units of seconds. More... | |
Additional Inherited Members | |
![]() | |
typedef uint8_t | Status |
The execution status of the coroutine, corresponding to the COROUTINE_YIELD(), COROUTINE_DELAY(), COROUTINE_AWAIT() and COROUTINE_END() macros. More... | |
A coroutine that reads lines from the Serial port, tokenizes the line on whitespace boundaries, and calls the appropriate command handler to handle the command.
Command have the form "command arg1 arg2 ...", where the 'arg*' can be any string.
The calling code is expected to provide a mapping of the command string (e.g. "list") to its command handler (CommandHandler). The CommandHandler is called with the number of arguments (argc) and the array of tokens (argv), just like the arguments of the C-language main() function.
The template parameters can be either a 'char' for C-strings or '__FlashStringHelper' for F() flash strings.
Definition at line 52 of file CommandDispatcher.h.
|
inline |
Constructor.
channel | A channel from the StringLineReader to this coroutine. |
printer | The output object, normally the global Serial object. |
commands | Array of CommandHandler pointers. |
numCommands | number of commands. |
argv | Array of (const char*) that will be used to hold the word tokens of a command line string. |
argvSize | The size of the argv array. Tokens which are beyond this limit will be silently dropped. |
prompt | If not null, print a prompt and echo the command entered by the user. If null, don't print prompt and don't echo. |
Definition at line 68 of file CommandDispatcher.h.
|
inlinevirtual |
|
protected |
Find and run the given command.
Definition at line 122 of file CommandDispatcher.cpp.
|
inline |
Find the CommandHandler of the given command name.
VisibleForTesting.
NOTE: this is currently a linear O(N) scan which is good enough for small number of commands. If we sorted the handlers, we could do a binary search for O(log(N)) and handle larger number of commands.
Definition at line 135 of file CommandDispatcher.h.
|
protected |
Handle the 'help' command.
Definition at line 55 of file CommandDispatcher.cpp.
|
protected |
Print helpString of specific cmd.
Returns true if cmd was found.
Definition at line 85 of file CommandDispatcher.cpp.
|
staticprotected |
Print help string for the given command.
Definition at line 95 of file CommandDispatcher.cpp.
|
protected |
Print the input line that caused an error along with its status code.
Definition at line 39 of file CommandDispatcher.cpp.
|
protected |
Tokenize the given line and run the command handler.
Definition at line 107 of file CommandDispatcher.cpp.
|
inlineoverridevirtual |
The body of the coroutine.
The COROUTINE macro creates a subclass of this class and puts the body of the coroutine into this method.
Implements ace_routine::Coroutine.
Definition at line 106 of file CommandDispatcher.h.
|
inlinestatic |
Tokenize the line, separating tokens delimited by whitespace (space, formfeed, carriage return, newline, tab, and vertical tab) and fill argv with each token until argvSize is reached.
Return the number of tokens filled in.
VisibleForTesting.
Definition at line 95 of file CommandDispatcher.h.