Merge branch 'testing' of https://github.com/arkhipenko/TaskScheduler

README.md

@@ -1,6 +1,6 @@
 # Task Scheduler
 ### Cooperative multitasking for Arduino, ESPx, STM32 and other microcontrollers
-#### Version 3.2.0: 2020-08-16 [Latest updates](https://github.com/arkhipenko/TaskScheduler/wiki/Latest-Updates)
+#### Version 3.2.2: 2020-12-14 [Latest updates](https://github.com/arkhipenko/TaskScheduler/wiki/Latest-Updates)
 
 [![arduino-library-badge](https://www.ardu-badge.com/badge/TaskScheduler.svg?)](https://www.ardu-badge.com/TaskScheduler)[![xscode](https://img.shields.io/badge/Available%20on-xs%3Acode-blue?style=?style=plastic&logo=appveyor&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAMAAACdt4HsAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAAZQTFRF////////VXz1bAAAAAJ0Uk5T/wDltzBKAAAAlUlEQVR42uzXSwqAMAwE0Mn9L+3Ggtgkk35QwcnSJo9S+yGwM9DCooCbgn4YrJ4CIPUcQF7/XSBbx2TEz4sAZ2q1RAECBAiYBlCtvwN+KiYAlG7UDGj59MViT9hOwEqAhYCtAsUZvL6I6W8c2wcbd+LIWSCHSTeSAAECngN4xxIDSK9f4B9t377Wd7H5Nt7/Xz8eAgwAvesLRjYYPuUAAAAASUVORK5CYII=)](https://xscode.com/arkhipenko/TaskScheduler)
 

keywords.txt

@@ -14,9 +14,12 @@ Task	KEYWORD1
 # Methods and Functions (KEYWORD2)
 #######################################
 
+abort	KEYWORD2
 addTask	KEYWORD2
 allowSleep	KEYWORD2
 Callback	KEYWORD2
+cancel	KEYWORD2
+canceled	KEYWORD2
 completed	KEYWORD2
 cpuLoadReset	KEYWORD2
 currentLts	KEYWORD2

library.json

@@ -16,7 +16,7 @@
       "maintainer": true
     }
   ],
-  "version": "3.2.0",
+  "version": "3.2.2",
   "frameworks": "arduino",
   "platforms": "*"
 }

library.properties

@@ -1,5 +1,5 @@
 name=TaskScheduler
-version=3.2.0
+version=3.2.2
 author=Anatoli Arkhipenko <arkhipenko@hotmail.com>
 maintainer=Anatoli Arkhipenko <arkhipenko@hotmail.com>
 sentence=Cooperative multitasking for Arduino, ESPx, STM32 and other microcontrollers.

src/TaskScheduler.h

@@ -179,7 +179,16 @@
 //
 // v3.2.0:
 //    2020-08-16 - feature: scheduling options
-
+//
+// v3.2.1:
+//    2020-10-04 - feature: Task.abort method. Stop task execution without calling OnDisable(). 
+//
+// v3.2.2:
+//    2020-12-14 - feature: enable and restart methods return true if task enabled 
+//                 feature: Task.cancel() method - disable task with a cancel flag (could be used for alt. path
+//                          processing in the onDisable method.
+//                 feature: Task.cancelled() method - indicates that task was disabled with a cancel() method.
+//
 
 #include <Arduino.h>
 
@@ -199,20 +208,21 @@ extern "C" {
 // The following "defines" control library functionality at compile time,
 // and should be used in the main sketch depending on the functionality required
 //
-// #define _TASK_TIMECRITICAL      // Enable monitoring scheduling overruns
-// #define _TASK_SLEEP_ON_IDLE_RUN // Enable 1 ms SLEEP_IDLE powerdowns between runs if no callback methods were invoked during the pass
-// #define _TASK_STATUS_REQUEST    // Compile with support for StatusRequest functionality - triggering tasks on status change events in addition to time only
-// #define _TASK_WDT_IDS           // Compile with support for wdt control points and task ids
-// #define _TASK_LTS_POINTER       // Compile with support for local task storage pointer
-// #define _TASK_PRIORITY          // Support for layered scheduling priority
-// #define _TASK_MICRO_RES         // Support for microsecond resolution
-// #define _TASK_STD_FUNCTION      // Support for std::function (ESP8266 ONLY)
-// #define _TASK_DEBUG             // Make all methods and variables public for debug purposes
-// #define _TASK_INLINE            // Make all methods "inline" - needed to support some multi-tab, multi-file implementations
-// #define _TASK_TIMEOUT           // Support for overall task timeout
-// #define _TASK_OO_CALLBACKS      // Support for callbacks via inheritance
-// #define _TASK_DEFINE_MILLIS     // Force forward declaration of millis() and micros() "C" style
-// #define _TASK_EXPOSE_CHAIN      // Methods to access tasks in the task chain
+// #define _TASK_TIMECRITICAL       // Enable monitoring scheduling overruns
+// #define _TASK_SLEEP_ON_IDLE_RUN  // Enable 1 ms SLEEP_IDLE powerdowns between runs if no callback methods were invoked during the pass
+// #define _TASK_STATUS_REQUEST     // Compile with support for StatusRequest functionality - triggering tasks on status change events in addition to time only
+// #define _TASK_WDT_IDS            // Compile with support for wdt control points and task ids
+// #define _TASK_LTS_POINTER        // Compile with support for local task storage pointer
+// #define _TASK_PRIORITY           // Support for layered scheduling priority
+// #define _TASK_MICRO_RES          // Support for microsecond resolution
+// #define _TASK_STD_FUNCTION       // Support for std::function (ESP8266 ONLY)
+// #define _TASK_DEBUG              // Make all methods and variables public for debug purposes
+// #define _TASK_INLINE             // Make all methods "inline" - needed to support some multi-tab, multi-file implementations
+// #define _TASK_TIMEOUT            // Support for overall task timeout
+// #define _TASK_OO_CALLBACKS       // Support for callbacks via inheritance
+// #define _TASK_DEFINE_MILLIS      // Force forward declaration of millis() and micros() "C" style
+// #define _TASK_EXPOSE_CHAIN       // Methods to access tasks in the task chain
+// #define _TASK_SCHEDULING_OPTIONS // Support for multiple scheduling options
 
  #ifdef _TASK_MICRO_RES
 
@@ -349,24 +359,26 @@ void StatusRequest::signalComplete(int aStatus) {
  *  @param: aStatusRequest - a pointer for the StatusRequest to wait for.
  *  If aStatusRequest is NULL, request for waiting is ignored, and the waiting task is not enabled.
  */
-void Task::waitFor(StatusRequest* aStatusRequest, unsigned long aInterval, long aIterations) {
+bool Task::waitFor(StatusRequest* aStatusRequest, unsigned long aInterval, long aIterations) {
     iStatusRequest = aStatusRequest;
     if ( iStatusRequest != NULL ) { // assign internal StatusRequest var and check if it is not NULL
         setIterations(aIterations);
         setInterval(aInterval);
         iStatus.waiting = _TASK_SR_NODELAY;  // no delay
-        enable();
+        return enable();
     }
+    return false;
 }
 
-void Task::waitForDelayed(StatusRequest* aStatusRequest, unsigned long aInterval, long aIterations) {
+bool Task::waitForDelayed(StatusRequest* aStatusRequest, unsigned long aInterval, long aIterations) {
     iStatusRequest = aStatusRequest;
     if ( iStatusRequest != NULL ) { // assign internal StatusRequest var and check if it is not NULL
         setIterations(aIterations);
         if ( aInterval ) setInterval(aInterval);  // For the dealyed version only set the interval if it was not a zero
         iStatus.waiting = _TASK_SR_DELAY;  // with delay equal to the current interval
-        enable();
+        return enable();
     }
+    return false;
 }
 #endif  // _TASK_STATUS_REQUEST
 
@@ -400,6 +412,7 @@ void Task::setOnDisable(TaskOnDisable aCallback) { iOnDisable = aCallback; }
 void Task::reset() {
     iStatus.enabled = false;
     iStatus.inonenable = false;
+    iStatus.canceled = false;
     iPreviousMillis = 0;
     iInterval = iDelay = 0;
     iPrev = NULL;
@@ -496,9 +509,10 @@ void Task::yieldOnce (TaskCallback aCallback) {
  *  schedules it for execution as soon as possible,
  *  and resets the RunCounter back to zero
  */
-void Task::enable() {
+bool Task::enable() {
     if (iScheduler) { // activation without active scheduler does not make sense
         iRunCounter = 0;
+        iStatus.canceled = false;
 
 #ifdef _TASK_OO_CALLBACKS
         if ( !iStatus.inonenable ) {
@@ -529,12 +543,14 @@ void Task::enable() {
             resetTimeout();
 #endif // _TASK_TIMEOUT
 
-#ifdef _TASK_STATUS_REQUEST
         if ( iStatus.enabled ) {
+#ifdef _TASK_STATUS_REQUEST
             iMyStatusRequest.setWaiting();
-        }
 #endif // _TASK_STATUS_REQUEST
+        }
+        return iStatus.enabled;
     }
+    return false;
 }
 
 /** Enables the task only if it was not enabled already
@@ -549,9 +565,10 @@ bool Task::enableIfNot() {
 /** Enables the task
  * and schedules it for execution after a delay = aInterval
  */
-void Task::enableDelayed(unsigned long aDelay) {
+bool Task::enableDelayed(unsigned long aDelay) {
     enable();
     delay(aDelay);
+    return iStatus.enabled;
 }
 
 #ifdef _TASK_TIMEOUT
@@ -644,21 +661,42 @@ bool Task::disable() {
     return (previousEnabled);
 }
 
+/** Aborts task execution
+ * Task will no longer be executed by the scheduler AND ondisable method will not be called
+ */
+void Task::abort() {
+    iStatus.enabled = false;
+    iStatus.inonenable = false;
+}
+
+
+/** Cancels task execution
+ * Task will no longer be executed by the scheduler. Ondisable method will be called after 'canceled' flag is set
+ */
+void Task::cancel() {
+    iStatus.canceled = true;
+    disable();
+}
+
+bool Task::canceled() {
+    return iStatus.canceled;
+}
+
 /** Restarts task
  * Task will run number of iterations again
  */
 
-void Task::restart() {
-    enable();
+bool Task::restart() {
     iIterations = iSetIterations;
+    return enable();
 }
 
 /** Restarts task delayed
  * Task will run number of iterations again
  */
-void Task::restartDelayed(unsigned long aDelay) {
-    enableDelayed(aDelay);
+bool Task::restartDelayed(unsigned long aDelay) {
     iIterations = iSetIterations;
+    return enableDelayed(aDelay);
 }
 
 bool Task::isFirstIteration() { return (iRunCounter <= 1); }

src/TaskSchedulerDeclarations.h

@@ -11,21 +11,21 @@
 // The following "defines" control library functionality at compile time,
 // and should be used in the main sketch depending on the functionality required
 //
-// #define _TASK_TIMECRITICAL           // Enable monitoring scheduling overruns
-// #define _TASK_SLEEP_ON_IDLE_RUN      // Enable 1 ms SLEEP_IDLE powerdowns between runs if no callback methods were invoked during the pass
-// #define _TASK_STATUS_REQUEST         // Compile with support for StatusRequest functionality - triggering tasks on status change events in addition to time only
-// #define _TASK_WDT_IDS                // Compile with support for wdt control points and task ids
-// #define _TASK_LTS_POINTER            // Compile with support for local task storage pointer
-// #define _TASK_PRIORITY               // Support for layered scheduling priority
-// #define _TASK_MICRO_RES              // Support for microsecond resolution
-// #define _TASK_STD_FUNCTION           // Support for std::function (ESP8266 ONLY)
-// #define _TASK_DEBUG                  // Make all methods and variables public for debug purposes
-// #define _TASK_INLINE                 // Make all methods "inline" - needed to support some multi-tab, multi-file implementations
-// #define _TASK_TIMEOUT                // Support for overall task timeout
-// #define _TASK_OO_CALLBACKS           // Support for callbacks via inheritance
-// #define _TASK_DEFINE_MILLIS          // Force forward declaration of millis() and micros() "C" style
-// #define _TASK_EXPOSE_CHAIN           // Methods to access tasks in the task chain
-// #define _TASK_SCHEDULING_OPTIONS     // Support for multiple scheduling options
+// #define _TASK_TIMECRITICAL       // Enable monitoring scheduling overruns
+// #define _TASK_SLEEP_ON_IDLE_RUN  // Enable 1 ms SLEEP_IDLE powerdowns between runs if no callback methods were invoked during the pass
+// #define _TASK_STATUS_REQUEST     // Compile with support for StatusRequest functionality - triggering tasks on status change events in addition to time only
+// #define _TASK_WDT_IDS            // Compile with support for wdt control points and task ids
+// #define _TASK_LTS_POINTER        // Compile with support for local task storage pointer
+// #define _TASK_PRIORITY           // Support for layered scheduling priority
+// #define _TASK_MICRO_RES          // Support for microsecond resolution
+// #define _TASK_STD_FUNCTION       // Support for std::function (ESP8266 ONLY)
+// #define _TASK_DEBUG              // Make all methods and variables public for debug purposes
+// #define _TASK_INLINE             // Make all methods "inline" - needed to support some multi-tab, multi-file implementations
+// #define _TASK_TIMEOUT            // Support for overall task timeout
+// #define _TASK_OO_CALLBACKS       // Support for callbacks via inheritance
+// #define _TASK_DEFINE_MILLIS      // Force forward declaration of millis() and micros() "C" style
+// #define _TASK_EXPOSE_CHAIN       // Methods to access tasks in the task chain
+// #define _TASK_SCHEDULING_OPTIONS // Support for multiple scheduling options
 
 class Scheduler;
 
@@ -119,9 +119,9 @@ typedef bool (*TaskOnEnable)();
 typedef struct  {
     bool  enabled    : 1;           // indicates that task is enabled or not.
     bool  inonenable : 1;           // indicates that task execution is inside OnEnable method (preventing infinite loops)
-
+    bool  canceled   : 1;           // indication that tast has been canceled prior to normal end of all iterations or regular call to disable()
 #ifdef _TASK_STATUS_REQUEST
-    uint8_t  waiting : 2;        // indication if task is waiting on the status request
+    uint8_t  waiting : 2;           // indication if task is waiting on the status request
 #endif
 
 #ifdef _TASK_TIMEOUT
@@ -164,16 +164,19 @@ class Task {
     INLINE bool timedOut();
 #endif
 
-    INLINE void enable();
+    INLINE bool enable();
     INLINE bool enableIfNot();
-    INLINE void enableDelayed(unsigned long aDelay=0);
-    INLINE void restart();
-    INLINE void restartDelayed(unsigned long aDelay=0);
+    INLINE bool enableDelayed(unsigned long aDelay=0);
+    INLINE bool restart();
+    INLINE bool restartDelayed(unsigned long aDelay=0);
 
     INLINE void delay(unsigned long aDelay=0);
     INLINE void forceNextIteration();
     INLINE bool disable();
+    INLINE void abort();
+    INLINE void cancel();
     INLINE bool isEnabled();
+    INLINE bool canceled();
 
 #ifdef _TASK_SCHEDULING_OPTIONS
     INLINE unsigned int getSchedulingOption() { return iOption; }
@@ -212,8 +215,8 @@ class Task {
 #endif  // _TASK_TIMECRITICAL
 
 #ifdef _TASK_STATUS_REQUEST
-    INLINE void waitFor(StatusRequest* aStatusRequest, unsigned long aInterval = 0, long aIterations = 1);
-    INLINE void waitForDelayed(StatusRequest* aStatusRequest, unsigned long aInterval = 0, long aIterations = 1);
+    INLINE bool waitFor(StatusRequest* aStatusRequest, unsigned long aInterval = 0, long aIterations = 1);
+    INLINE bool waitForDelayed(StatusRequest* aStatusRequest, unsigned long aInterval = 0, long aIterations = 1);
     INLINE StatusRequest* getStatusRequest() ;
     INLINE StatusRequest* getInternalStatusRequest() ;
 #endif  // _TASK_STATUS_REQUEST