Merge branch 'mc/parameterize-handler-argument'

* mc/parameterize-handler-argument:
  examples:full: add parametrized timer example
  README: update with template handler usage
  src/timer: parameterize handler argument type

Author: contrem

README.md

@@ -15,6 +15,7 @@ Or using the *Timer* constructors for different task limits / time resolution
 ```cpp
 Timer<10> timer; // 10 concurrent tasks, using millis as resolution
 Timer<10, micros> timer; // 10 concurrent tasks, using micros as resolution
+Timer<10, micros, int> timer; // 10 concurrent tasks, using micros as resolution, with handler argument of type int
 ```
 
 Call *timer*.**tick()** in the loop function
@@ -65,33 +66,36 @@ timer.in(1000, [](void *argument) -> bool { return argument; }, argument);
 
 ```cpp
 /* Constructors */
-/* Create a timer object with default settings - millis resolution, TIMER_MAX_TASKS (=16) task slots */
+/* Create a timer object with default settings:
+   millis resolution, TIMER_MAX_TASKS (=16) task slots, T = void *
+*/
 Timer<> timer_create_default(); // auto timer = timer_create_default();
 
 /* Create a timer with max_tasks slots and time_func resolution */
-Timer<size_t max_tasks = TIMER_MAX_TASKS, unsigned long (*time_func)(void) = millis> timer;
+Timer<size_t max_tasks = TIMER_MAX_TASKS, unsigned long (*time_func)(void) = millis, typename T = void *> timer;
 Timer<> timer; // Equivalent to: auto timer = timer_create_default()
 Timer<10> timer; // Timer with 10 task slots
 Timer<10, micros> timer; // timer with 10 task slots and microsecond resolution
+Timer<10, micros, int> timer; // timer with 10 task slots, microsecond resolution, and handler argument type int
 
-/* Signature for handler functions */
-bool handler(void *argument);
+/* Signature for handler functions - T = void * by default */
+bool handler(T argument);
 
 /* Timer Methods */
 /* Ticks the timer forward, returns the ticks until next event, or 0 if none */
-unsigned int tick(); // call this function in loop()
+unsigned long tick(); // call this function in loop()
 
 /* Calls handler with opaque as argument in delay units of time */
 Timer<>::Task
-in(unsigned long delay, handler_t handler, void *opaque = NULL);
+in(unsigned long delay, handler_t handler, T opaque = T());
 
 /* Calls handler with opaque as argument at time */
 Timer<>::Task
-at(unsigned long time, handler_t handler, void *opaque = NULL);
+at(unsigned long time, handler_t handler, T opaque = T());
 
 /* Calls handler with opaque as argument every interval units of time */
 Timer<>::Task
-every(unsigned long interval, handler_t handler, void *opaque = NULL);
+every(unsigned long interval, handler_t handler, T opaque = T());
 
 /* Cancel a timer task */
 void cancel(Timer<>::Task &task);

examples/full/full.ino

@@ -16,15 +16,20 @@ auto timer = timer_create_default(); // create a timer with default settings
 Timer<> default_timer; // save as above
 
 // create a timer that can hold 1 concurrent task, with microsecond resolution
-Timer<1, micros> u_timer;
+// and a custom handler type of 'const char *
+Timer<1, micros, const char *> u_timer;
+
+
+// create a timer that holds 16 tasks, with millisecond resolution,
+// and a custom handler type of 'const char *
+Timer<16, millis, const char *> t_timer;
 
 bool toggle_led(void *) {
   digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN)); // toggle the LED
   return true; // repeat? true
 }
 
-bool print_message(void *msg) {
-  const char *m = (const char *)msg;
+bool print_message(const char *m) {
   Serial.print("print_message: ");
   Serial.println(m);
   return true; // repeat? true
@@ -54,28 +59,29 @@ void setup() {
 
   // call the print_message function every 1000 millis (1 second),
   // passing it an argument string
-  timer.every(1000, print_message, (void *)"called every second");
+  t_timer.every(1000, print_message, "called every second");
 
   // call the print_message function in five seconds
-  timer.in(5000, print_message, (void *)"delayed five seconds");
+  t_timer.in(5000, print_message, "delayed five seconds");
 
   // call the print_message function at time + 10 seconds
-  timer.at(millis() + 10000, print_message, (void *)"call at millis() + 10 seconds");
+  t_timer.at(millis() + 10000, print_message, "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");
+  u_timer.in(2000000, print_message, "delayed two seconds using microseconds");
 
-  if (!u_timer.in(5000, print_message, (void *)"never printed")) {
+  if (!u_timer.in(5000, print_message, "never printed")) {
   /* this fails because we created u_timer with only 1 concurrent task slot */
     Serial.println("Failed to add microsecond event - timer full");
   }
 }
 
 void loop() {
   timer.tick(); // tick the timer
+  t_timer.tick();
   u_timer.tick();
 }

src/timer.h

@@ -47,32 +47,33 @@
 
 template <
     size_t max_tasks = TIMER_MAX_TASKS, /* max allocated tasks */
-    unsigned long (*time_func)() = millis /* time function for timer */
+    unsigned long (*time_func)() = millis, /* time function for timer */
+    typename T = void * /* handler argument type */
 >
 class Timer {
   public:
 
     typedef uintptr_t Task; /* public task handle */
-    typedef bool (*handler_t)(void *opaque); /* task handler func signature */
+    typedef bool (*handler_t)(T opaque); /* task handler func signature */
 
     /* Calls handler with opaque as argument in delay units of time */
     Task
-    in(unsigned long delay, handler_t h, void *opaque = NULL)
+    in(unsigned long delay, handler_t h, T opaque = T())
     {
         return task_id(add_task(time_func(), delay, h, opaque));
     }
 
     /* Calls handler with opaque as argument at time */
     Task
-    at(unsigned long time, handler_t h, void *opaque = NULL)
+    at(unsigned long time, handler_t h, T opaque = T())
     {
         const unsigned long now = time_func();
         return task_id(add_task(now, time - now, h, opaque));
     }
 
     /* Calls handler with opaque as argument every interval units of time */
     Task
-    every(unsigned long interval, handler_t h, void *opaque = NULL)
+    every(unsigned long interval, handler_t h, T opaque = T())
     {
         return task_id(add_task(time_func(), interval, h, opaque, interval));
     }
@@ -129,7 +130,7 @@ class Timer {
 
     struct task {
         handler_t handler; /* task handler callback func */
-        void *opaque; /* argument given to the callback handler */
+        T opaque; /* argument given to the callback handler */
         unsigned long start,
                       expires; /* when the task expires */
         size_t repeat, /* repeat task */
@@ -141,7 +142,7 @@ class Timer {
     remove(struct task *task)
     {
         task->handler = NULL;
-        task->opaque = NULL;
+        task->opaque = T();
         task->start = 0;
         task->expires = 0;
         task->repeat = 0;
@@ -172,7 +173,7 @@ class Timer {
     inline
     struct task *
     add_task(unsigned long start, unsigned long expires,
-             handler_t h, void *opaque, bool repeat = 0)
+             handler_t h, T opaque, bool repeat = 0)
     {
         struct task * const slot = next_task_slot();