Tip: Confirm your timer tasks return true to repeat

[philj404]

This is probably worth pointing out in a Q&A. Originally discussed in #24.

Make sure your tasks always return true to ensure they repeat. For example:

//////////////////////////////////////////////////////
// EXAMPLE FOR TIMER TASKS:
//   the function declares it returns 'bool'
//   the function actually returns a bool (returns true)
//
bool do_my_thing(void *) {
    // your code here...
    return true; // do it again too
}

The compiler may not notice if there is a problem. I have run into Arduino configurations (ATmega328P) which did not detect "this function does not return a value but it should have".

The following sketch compiles and downloads for ATmega328P, even though there are problems with it:

/*
    Demonstrate compiler warnings that are easy to miss.
    Three different tasks, two with bugs.
    
    Based on arduino-timer/blink.

    philj404 14feb2021
*/

#include <arduino-timer.h>

auto timer = timer_create_default(); // create a timer with default settings

//////////////////////////////////////////////////////
// CORRECTLY CONFIGURED FOR TIMER TASKS:
//   the function declares it returns 'bool'
//   the function actually returns a bool (returns true)
//
bool toggle_led(void *) {
    digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN)); // toggle the LED
    return true; // repeat? true
}

//////////////////////////////////////////////////////
// function does not declare a return value
//
void bug_toggle_returns_void(void *) {
    digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN)); // toggle the LED
    return true; // the void declaration ignores this return value
}

//////////////////////////////////////////////////////
// function does not return a value
//
bool bug_toggle_forgot_to_return_bool(void *) {
    digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN)); // toggle the LED
    //"return true;" missing; did you see a warning?
}

void setup() {
    pinMode(LED_BUILTIN, OUTPUT); // set LED pin to OUTPUT

    // call the toggle_led function about every second
    timer.every(1000, toggle_led);

    timer.every(1001, bug_toggle_returns_void);
    timer.every( 999, bug_toggle_forgot_to_return_bool);
}

void loop() {
    timer.tick(); // tick the timer
}

[petkusj]

Phil, this raises the question: if you've canceled an every task, should you return false? I am canceling my tasks in the function that is called. Or, for that matter, if you've created an in task, after the function has been called, do you return false or true?

Jennifer

[philj404]

timer.tick() checks each pending task one at a time, sees if it is ready, and if so executes it.

So if your repetitive taskA wants to cancel itself, all it needs to do is return false. (It should not call timer.cancel().)

Non-repetitive tasks (the timer.in(...) and timer.at(...) tasks) don't need to cancel themselves because they only run once anyway. Since they are only going to run once it does not matter what they return.

If a different task taskB is running and discovers it needs to cancel obsolete taskA, then taskA is not running. taskB can cancel pending taskA using timer.cancel(...). Since taskA was not running and it got cancelled, it doesn't matter what it would have returned.

[petkusj]

Thanks, that's really great info and in my opinion, ought to be in the README file.

Also, I think this means you shouldn't cancel tasks in the function called by the task, which is what I was trying to do.

Thanks again,

Jennifer

[philj404]

It is very hard to anticipate what issues others will have with your library (and put in the README). Everyone has a different application with different requirements. Few people ever agree on what is "obvious".

We all have different blind spots... but which blind spots are the most common? Those are the areas that need the most support. It might take a few question/answer cycles to recognize a recurring theme. Eventually we might learn that something was not so "obvious" after all.

These Q&A discussions should be able to help. The advantage of the Q&A format is that we don't have to wait for a release for clarification... and we don't need extra releases just to update READMEs.

[philj404]

This tip is a suggested answer extracted from #24.