Merge branch 'mc/cancel'

* mc/cancel:
  timer:cancel: handle cancel of expired tasks
  timer:keywords: add Task type, and cancel method
  timer:examples:full: add cancel example
  timer:README: update for cancel method
  timer: add cancel method

Author: contrem

README.md

@@ -49,6 +49,12 @@ timer.every(interval, function_to_call);
 timer.every(interval, function_to_call, argument); // with argument
 ```
 
+To **cancel** a *Task*
+```cpp
+auto task = timer.in(delay, function_to_call);
+timer.cancel(task);
+```
+
 Be fancy with **lambdas**
 ```cpp
 timer.in(1000, [](void*) -> bool { return false; });
@@ -76,13 +82,19 @@ bool handler(void *argument);
 void tick();
 
 /* Calls handler with opaque as argument in delay units of time */
-bool in(unsigned long delay, handler_t handler, void *opaque = NULL);
+Timer<>::Task
+in(unsigned long delay, handler_t handler, void *opaque = NULL);
 
 /* Calls handler with opaque as argument at time */
-bool at(unsigned long time, handler_t handler, void *opaque = NULL);
+Timer<>::Task
+at(unsigned long time, handler_t handler, void *opaque = NULL);
 
 /* Calls handler with opaque as argument every interval units of time */
-bool every(unsigned long interval, handler_t handler, void *opaque = NULL);
+Timer<>::Task
+every(unsigned long interval, handler_t handler, void *opaque = NULL);
+
+/* Cancel a timer task */
+void cancel(Timer<>::Task &task);
 ```
 
 ### Installation
@@ -129,7 +141,9 @@ Currently only a software timer. Any blocking code delaying *timer*.**tick()** w
 
 The library does not do any dynamic memory allocation.
 
-The number of concurrent tasks is a compile time constant, meaning there is a limit to the number of concurrent tasks. The **in / at / every** functions return **false** if the *Timer* is full.
+The number of concurrent tasks is a compile time constant, meaning there is a limit to the number of concurrent tasks. The **in / at / every** functions return **NULL** if the *Timer* is full.
+
+A *Task* value is valid only for the timer that created it, and only for the lifetime of that timer.
 
 Change the number of concurrent tasks using the *Timer* constructors. Save memory by reducing the number, increase memory use by having more. The default is **TIMER_MAX_TASKS** which is currently 16.
 

examples/full/full.ino

@@ -6,6 +6,7 @@
  *  - Setting a different number of tasks with microsecond resolution
  *  - disabling a repeated function
  *  - running a function after a delay
+ *  - cancelling a task
  *
  */
 
@@ -61,6 +62,10 @@ void setup() {
   // call the print_message function at time + 10 seconds
   timer.at(millis() + 10000, print_message, (void *)"call at millis() + 10 seconds");
 
+  // call the toggle_led function every 500 millis (half second)
+  auto task = timer.every(500, toggle_led);
+  timer.cancel(task); // this task is now cancelled, and will not run
+
   // call print_message in 2 seconds, but with microsecond resolution
   u_timer.in(2000000, print_message, (void *)"delayed two seconds using microseconds");
 

keywords.txt

@@ -7,6 +7,7 @@
 #######################################
 
 Timer	KEYWORD1
+Task	KEYWORD1
 handler_t	KEYWORD1
 
 #######################################
@@ -17,6 +18,7 @@ in	KEYWORD2
 at	KEYWORD2
 every	KEYWORD2
 tick	KEYWORD2
+cancel	KEYWORD2
 
 #######################################
 # Instances (KEYWORD2)

src/timer.h

@@ -52,28 +52,47 @@ template <
 class Timer {
   public:
 
+    typedef uintptr_t Task; /* public task handle */
     typedef bool (*handler_t)(void *opaque); /* task handler func signature */
 
     /* Calls handler with opaque as argument in delay units of time */
-    bool
+    Task
     in(unsigned long delay, handler_t h, void *opaque = NULL)
     {
-        return add_task(time_func(), delay, h, opaque);
+        return task_id(add_task(time_func(), delay, h, opaque));
     }
 
     /* Calls handler with opaque as argument at time */
-    bool
+    Task
     at(unsigned long time, handler_t h, void *opaque = NULL)
     {
         const unsigned long now = time_func();
-        return add_task(now, time - now, h, opaque);
+        return task_id(add_task(now, time - now, h, opaque));
     }
 
     /* Calls handler with opaque as argument every interval units of time */
-    bool
+    Task
     every(unsigned long interval, handler_t h, void *opaque = NULL)
     {
-        return add_task(time_func(), interval, h, opaque, interval);
+        return task_id(add_task(time_func(), interval, h, opaque, interval));
+    }
+
+    /* Cancel the timer task */
+    void
+    cancel(Task &task)
+    {
+        if (!task) return;
+
+        for (size_t i = 0; i < max_tasks; ++i) {
+            struct task * const t = &tasks[i];
+
+            if (t->handler && (t->id ^ task) == (uintptr_t)t) {
+                remove(t);
+                break;
+            }
+        }
+
+        task = NULL;
     }
 
     /* Ticks the timer forward - call this function in loop() */
@@ -117,12 +136,15 @@ class Timer {
 
   private:
 
+    size_t ctr;
+
     struct task {
         handler_t handler; /* task handler callback func */
         void *opaque; /* argument given to the callback handler */
         unsigned long start,
-                      expires, /* when the task expires */
-                      repeat; /* repeat task */
+                      expires; /* when the task expires */
+        size_t repeat, /* repeat task */
+               id;
     } tasks[max_tasks];
 
     inline
@@ -134,6 +156,16 @@ class Timer {
         task->start = 0;
         task->expires = 0;
         task->repeat = 0;
+        task->id = 0;
+    }
+
+    inline
+    Task
+    task_id(const struct task * const t)
+    {
+        const Task id = (uintptr_t)t;
+
+        return id ? id ^ t->id : id;
     }
 
     inline
@@ -157,6 +189,9 @@ class Timer {
 
         if (!slot) return NULL;
 
+        if (++ctr == 0) ++ctr; // overflow
+
+        slot->id = ctr;
         slot->handler = h;
         slot->opaque = opaque;
         slot->start = start;