v2.3.0 - new timeUntilNextIteration() method within Scheduler class

- new timeUntilNextIteration() method within Scheduler class - inquire
when a particlar task is scheduled to run next time

README

@@ -1,5 +1,5 @@
 Task Scheduler – cooperative multitasking for Arduino and ESP8266 microcontrollers
-Version 2.2.1: 2016-12-20
+Version 2.3.0: 2017-02-24
 
 If you find TaskScheduler useful for your Arduino project, please drop me an email: arkhipenko@hotmail.com
 ----------------------------------------------------------------------------------------------------------
@@ -70,6 +70,10 @@ Check out what TaskScheduler can do:
 
 Changelog:
 =========
+v2.3.0:
+    2017-02-24 - new timeUntilNextIteration() method within Scheduler class - inquire when a particlar task is 
+                 scheduled to run next time
+				 
 v2.2.1:
     2016-11-30 - inlined constructors. Added "yield()" and "yieldOnce()" functions to easily break down and
 				 chain back together long running callback methods

keywords.txt

@@ -22,6 +22,7 @@ enableAll	KEYWORD2
 currentTask	KEYWORD2
 currentLts	KEYWORD2
 execute	KEYWORD2
+timeUntilNextIteration	KEYWORD2
 startNow	KEYWORD2
 allowSleep	KEYWORD2
 enable	KEYWORD2

library.json

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

library.properties

@@ -1,8 +1,8 @@
 name=TaskScheduler
-version=2.2.1
+version=2.3.0
 author=Anatoli Arkhipenko <arkhipenko@hotmail.com>
 maintainer=Anatoli Arkhipenko <arkhipenko@hotmail.com>
-sentence=A light-weight cooperative multitasking library for arduino microcontrollers.
+sentence=A light-weight cooperative multitasking library for arduino and esp8266 microcontrollers.
 paragraph=Supports: periodic task execution (with dynamic execution period in milliseconds or microseconds – frequency of execution), number of iterations (limited or infinite number of iterations), execution of tasks in predefined sequence, dynamic change of task execution parameters (frequency, number of iterations, callback methods), power saving via entering IDLE sleep mode when tasks are not scheduled to run, event-driven task invocation via Status Request object, task IDs and Control Points for error handling and watchdog timer, Local Task Storage pointer (allowing use of same callback code for multiple tasks), layered task prioritization.
 category=Timing
 url=https://github.com/arkhipenko/TaskScheduler.git

src/TaskScheduler.h

@@ -103,6 +103,10 @@
 //                 back together long running callback methods
 //    2016-12-16 - added "getCount()" to StatusRequest objects, made every task StatusRequest enabled. 
 //                 Internal StatusRequest objects are accessible via "getInternalStatusRequest()" method. 
+//
+// v2.3.0:
+//    2017-02-24 - new timeUntilNextIteration() method within Scheduler class - inquire when a particlar task is 
+//                 scheduled to run next time
 
 #include <Arduino.h>
 
@@ -306,9 +310,10 @@ class Scheduler {
 		inline void deleteTask(Task& aTask);
 		inline void disableAll(bool aRecursive = true);
 		inline void enableAll(bool aRecursive = true);
-		inline bool execute();			// Returns true if at none of the tasks' callback methods was invoked (true if idle run)
+		inline bool execute();			// Returns true if none of the tasks' callback methods was invoked (true = idle run)
 		inline void startNow(bool aRecursive = true); 			// reset ALL active tasks to immediate execution NOW.
 		inline Task& currentTask() {return *iCurrent; }
+		inline long timeUntilNextIteration(Task& aTask); // return number of ms until next iteration of a given Task
 #ifdef _TASK_SLEEP_ON_IDLE_RUN
 		inline void allowSleep(bool aState = true);
 #endif  // _TASK_SLEEP_ON_IDLE_RUN
@@ -741,6 +746,29 @@ void Scheduler::startNow( bool aRecursive ) {
 #endif  // _TASK_PRIORITY
 }
 
+/** Returns number millis or micros until next scheduled iteration of a given task
+ *
+ * @param aTask - reference to task which next iteration is in question
+ */
+long Scheduler::timeUntilNextIteration(Task& aTask) {
+	
+#ifdef _TASK_STATUS_REQUEST
+	
+	StatusRequest *s = aTask.getStatusRequest();
+	if ( s != NULL && s->pending() ) 
+		return (-1);	// cannot be determined
+#endif
+	if ( !aTask.isEnabled() )
+		return (-1); 	// cannot be determined
+	
+	long d = (long) aTask.iDelay - ( (long) ((_TASK_TIME_FUNCTION() - aTask.iPreviousMillis)) );
+	
+	if ( d < 0 ) 
+		return (0); // Task will run as soon as possible
+	return ( d );
+}
+
+
 /** Makes one pass through the execution chain.
  * Tasks are executed in the order they were added to the chain
  * There is no concept of priority