From 6237fd61d7541f63fbd3fe68f5aef323a4e1036f Mon Sep 17 00:00:00 2001 From: david gauchard Date: Thu, 27 Jun 2019 00:29:50 +0200 Subject: [PATCH 1/2] add documentation to scheduled functions --- cores/esp8266/Schedule.h | 33 +++++++++++++++++++++++++++------ 1 file changed, 27 insertions(+), 6 deletions(-) diff --git a/cores/esp8266/Schedule.h b/cores/esp8266/Schedule.h index 3fcb2810cc..cb90683a6b 100644 --- a/cores/esp8266/Schedule.h +++ b/cores/esp8266/Schedule.h @@ -5,6 +5,21 @@ #define SCHEDULED_FN_MAX_COUNT 32 +// The purpose of scheduled functions is to trigger, from SYS stack (like in +// an interrupt or a system event), registration of user code to be executed +// in user stack (called CONT stack) without the common restrictions from +// system context. Details are below. + +// The purpose of recurrent scheduled function is to independantly execute +// user code in CONT stack on a regular basis. +// It has been introduced with ethernet service in mind, it can also be used +// for all libraries in the need of a regular `libdaemon_handlestuff()`. +// It allows these services to be run even from a user loop not going back +// to `loop()`. +// Ticker + scheduled function offer the same service but recurrent +// scheduled function happen more often: every yield() (vs every loop()), +// and time resolution is microsecond (vs millisecond). Details are below. + // scheduled functions called once: // // * internal queue is FIFO. @@ -17,27 +32,33 @@ // * There is no mechanism for cancelling scheduled functions. // * `yield` can be called from inside lambdas. // * Returns false if the number of scheduled functions exceeds -// SCHEDULED_FN_MAX_COUNT. +// SCHEDULED_FN_MAX_COUNT (or memory shortage). // * Run the lambda only once next time. +// * A scheduled function can schedule a function. bool schedule_function (const std::function& fn); // Run all scheduled functions. -// Use this function if your are not using `loop`, or `loop` does not return -// on a regular basis. +// Use this function if your are not using `loop`, +// or `loop` does not return on a regular basis. void run_scheduled_functions(); // recurrent scheduled function: // -// * internal queue if not FIFO. +// * Internal queue may not be a FIFO. // * Run the lambda periodically about every microseconds until // it returns false. // * Note that it may be more than microseconds between calls if // `yield` is not called frequently, and therefore should not be used for // timing critical operations. -// * There is no mechanism for cancelling recurrent scheduled functions. -// * long running operations or yield() or delay() are not allowed in the lambda. +// * Please ensure variables or instances used from inside lambda will exist +// when lambda is later called. +// * There is no mechanism for externally cancelling recurrent scheduled +// functions. However a user function returning false will cancel itself. +// * Long running operations or yield() or delay() are not allowed in the +// recurrent function. +// * A recurrent scheduled function can schedule recurrent functions (if ever needed). bool schedule_recurrent_function_us (const std::function& fn, uint32_t repeat_us); From bcb4088ba84fa70b95a419ccb98ff69f5165bec4 Mon Sep 17 00:00:00 2001 From: David Gauchard Date: Thu, 27 Jun 2019 10:57:30 +0200 Subject: [PATCH 2/2] update: recurrent function cannot schedule another recurrent function per #6235 example --- cores/esp8266/Schedule.cpp | 7 ++----- cores/esp8266/Schedule.h | 3 ++- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/cores/esp8266/Schedule.cpp b/cores/esp8266/Schedule.cpp index f8d7b67916..5e56ac58df 100644 --- a/cores/esp8266/Schedule.cpp +++ b/cores/esp8266/Schedule.cpp @@ -98,12 +98,9 @@ bool schedule_recurrent_function_us (const std::function& fn, uint32 item->mFunc = fn; if (rFirst) - { item->mNext = rFirst; - rFirst = item; - } - else - rFirst = item; + + rFirst = item; return true; } diff --git a/cores/esp8266/Schedule.h b/cores/esp8266/Schedule.h index cb90683a6b..50fc88fc8b 100644 --- a/cores/esp8266/Schedule.h +++ b/cores/esp8266/Schedule.h @@ -58,7 +58,8 @@ void run_scheduled_functions(); // functions. However a user function returning false will cancel itself. // * Long running operations or yield() or delay() are not allowed in the // recurrent function. -// * A recurrent scheduled function can schedule recurrent functions (if ever needed). +// * A recurrent function currently must not schedule another recurrent +// functions. bool schedule_recurrent_function_us (const std::function& fn, uint32_t repeat_us);