Add support for deferred executors. (#14859)

* Add support for deferred executors.

* More docs.

* Include from quantum.h

* Cleanup.

* Parameter checks

* Comments.

* qmk format-c

* I accidentally a few words.

* API name change.

* Apply suggestions from code review

Co-authored-by: Sergey Vlasov <sigprof@gmail.com>

* Review comments.

* qmk format-c

* Review comments.

Co-authored-by: Sergey Vlasov <sigprof@gmail.com>

builddefs/generic_features.mk

@@ -19,6 +19,7 @@ GRAVE_ESC_ENABLE ?= yes
 GENERIC_FEATURES = \
     COMBO \
     COMMAND \
+    DEFERRED_EXEC \
     DIGITIZER \
     DIP_SWITCH \
     DYNAMIC_KEYMAP \

docs/config_options.md

@@ -446,6 +446,8 @@ Use these to enable or disable building certain features. The more you have enab
   * Forces the keyboard to wait for a USB connection to be established before it starts up
 * `NO_USB_STARTUP_CHECK`
   * Disables usb suspend check after keyboard startup. Usually the keyboard waits for the host to wake it up before any tasks are performed. This is useful for split keyboards as one half will not get a wakeup call but must send commands to the master.
+* `DEFERRED_EXEC_ENABLE`
+  * Enables deferred executor support -- timed delays before callbacks are invoked. See [deferred execution](custom_quantum_functions.md#deferred-execution) for more information.
 
 ## USB Endpoint Limitations
 

docs/custom_quantum_functions.md

@@ -405,3 +405,69 @@ And you're done.  The RGB layer indication will only work if you want it to. And
 * Keymap: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)` and `void eeconfig_update_user(uint32_t val)`
 
 The `val` is the value of the data that you want to write to EEPROM.  And the `eeconfig_read_*` function return a 32 bit (DWORD) value from the EEPROM. 
+
+### Deferred Execution :id=deferred-execution
+
+QMK has the ability to execute a callback after a specified period of time, rather than having to manually manage timers.
+
+#### Deferred executor callbacks
+
+All _deferred executor callbacks_ have a common function signature and look like:
+
+```c
+uint32_t my_callback(uint32_t trigger_time, void *cb_arg) {
+    /* do something */
+    bool repeat = my_deferred_functionality();
+    return repeat ? 500 : 0;
+}
+```
+
+The first argument `trigger_time` is the intended time of execution. If other delays prevent executing at the exact trigger time, this allows for "catch-up" or even skipping intervals, depending on the required behaviour.
+
+The second argument `cb_arg` is the same argument passed into `defer_exec()` below, and can be used to access state information from the original call context.
+
+The return value is the number of milliseconds to use if the function should be repeated -- if the callback returns `0` then it's automatically unregistered. In the example above, a hypothetical `my_deferred_functionality()` is invoked to determine if the callback needs to be repeated -- if it does, it reschedules for a `500` millisecond delay, otherwise it informs the deferred execution background task that it's done, by returning `0`.
+
+?> Note that the returned delay will be applied to the intended trigger time, not the time of callback invocation. This allows for generally consistent timing even in the face of occasional late execution.
+
+#### Deferred executor registration
+
+Once a callback has been defined, it can be scheduled using the following API:
+
+```c
+deferred_token my_token = defer_exec(1500, my_callback, NULL);
+```
+
+The first argument is the number of milliseconds to wait until executing `my_callback` -- in the case above, `1500` milliseconds, or 1.5 seconds.
+
+The third parameter is the `cb_arg` that gets passed to the callback at the point of execution. This value needs to be valid at the time the callback is invoked -- a local function value will be destroyed before the callback is executed and should not be used. If this is not required, `NULL` should be used.
+
+The return value is a `deferred_token` that can consequently be used to cancel the deferred executor callback before it's invoked. If a failure occurs, the returned value will be `INVALID_DEFERRED_TOKEN`. Usually this will be as a result of supplying `0` to the delay, or a `NULL` for the callback. The other failure case is if there are too many deferred executions "in flight" -- this can be increased by changing the limit, described below.
+
+#### Extending a deferred execution
+
+The `deferred_token` returned by `defer_exec()` can be used to extend a the duration a pending execution waits before it gets invoked:
+```c
+// This will re-delay my_token's future execution such that it is invoked 800ms after the current time
+extend_deferred_exec(my_token, 800);
+```
+
+#### Cancelling a deferred execution
+
+The `deferred_token` returned by `defer_exec()` can be used to cancel a pending execution before it gets invoked:
+```c
+// This will cancel my_token's future execution
+cancel_deferred_exec(my_token);
+```
+
+Once a token has been canceled, it should be considered invalid. Reusing the same token is not supported.
+
+#### Deferred callback limits
+
+There are a maximum number of deferred callbacks that can be scheduled, controlled by the value of the define `MAX_DEFERRED_EXECUTORS`.
+
+If registrations fail, then you can increase this value in your keyboard or keymap `config.h` file, for example to 16 instead of the default 8:
+
+```c
+#define MAX_DEFERRED_EXECUTORS 16
+```

docs/getting_started_make_guide.md

@@ -145,6 +145,10 @@ Lets you replace the default matrix scanning routine with your own code. For fur
 
 Lets you replace the default key debouncing routine with an alternative one. If `custom` you will need to provide your own implementation.
 
+`DEFERRED_EXEC_ENABLE`
+
+Enables deferred executor support -- timed delays before callbacks are invoked. See [deferred execution](custom_quantum_functions.md#deferred-execution) for more information.
+
 ## Customizing Makefile Options on a Per-Keymap Basis
 
 If your keymap directory has a file called `rules.mk` any options you set in that file will take precedence over other `rules.mk` options for your particular keyboard.

quantum/deferred_exec.c

@@ -0,0 +1,152 @@
+// Copyright 2021 Nick Brassel (@tzarc)
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+#include <stddef.h>
+#include <timer.h>
+#include <deferred_exec.h>
+
+#ifndef MAX_DEFERRED_EXECUTORS
+#    define MAX_DEFERRED_EXECUTORS 8
+#endif
+
+typedef struct deferred_executor_t {
+    deferred_token         token;
+    uint32_t               trigger_time;
+    deferred_exec_callback callback;
+    void *                 cb_arg;
+} deferred_executor_t;
+
+static deferred_token      current_token                     = 0;
+static uint32_t            last_deferred_exec_check          = 0;
+static deferred_executor_t executors[MAX_DEFERRED_EXECUTORS] = {0};
+
+static inline bool token_can_be_used(deferred_token token) {
+    if (token == INVALID_DEFERRED_TOKEN) {
+        return false;
+    }
+    for (int i = 0; i < MAX_DEFERRED_EXECUTORS; ++i) {
+        if (executors[i].token == token) {
+            return false;
+        }
+    }
+    return true;
+}
+
+static inline deferred_token allocate_token(void) {
+    deferred_token first = ++current_token;
+    while (!token_can_be_used(current_token)) {
+        ++current_token;
+        if (current_token == first) {
+            // If we've looped back around to the first, everything is already allocated (yikes!). Need to exit with a failure.
+            return INVALID_DEFERRED_TOKEN;
+        }
+    }
+    return current_token;
+}
+
+deferred_token defer_exec(uint32_t delay_ms, deferred_exec_callback callback, void *cb_arg) {
+    // Ignore queueing if it's a zero-time delay, or invalid callback
+    if (delay_ms == 0 || !callback) {
+        return INVALID_DEFERRED_TOKEN;
+    }
+
+    // Find an unused slot and claim it
+    for (int i = 0; i < MAX_DEFERRED_EXECUTORS; ++i) {
+        deferred_executor_t *entry = &executors[i];
+        if (entry->token == INVALID_DEFERRED_TOKEN) {
+            // Work out the new token value, dropping out if none were available
+            deferred_token token = allocate_token();
+            if (token == INVALID_DEFERRED_TOKEN) {
+                return false;
+            }
+
+            // Set up the executor table entry
+            entry->token        = current_token;
+            entry->trigger_time = timer_read32() + delay_ms;
+            entry->callback     = callback;
+            entry->cb_arg       = cb_arg;
+            return current_token;
+        }
+    }
+
+    // None available
+    return INVALID_DEFERRED_TOKEN;
+}
+
+bool extend_deferred_exec(deferred_token token, uint32_t delay_ms) {
+    // Ignore queueing if it's a zero-time delay, or the token is not valid
+    if (delay_ms == 0 || token == INVALID_DEFERRED_TOKEN) {
+        return false;
+    }
+
+    // Find the entry corresponding to the token
+    for (int i = 0; i < MAX_DEFERRED_EXECUTORS; ++i) {
+        deferred_executor_t *entry = &executors[i];
+        if (entry->token == token) {
+            // Found it, extend the delay
+            entry->trigger_time = timer_read32() + delay_ms;
+            return true;
+        }
+    }
+
+    // Not found
+    return false;
+}
+
+bool cancel_deferred_exec(deferred_token token) {
+    // Ignore request if the token is not valid
+    if (token == INVALID_DEFERRED_TOKEN) {
+        return false;
+    }
+
+    // Find the entry corresponding to the token
+    for (int i = 0; i < MAX_DEFERRED_EXECUTORS; ++i) {
+        deferred_executor_t *entry = &executors[i];
+        if (entry->token == token) {
+            // Found it, cancel and clear the table entry
+            entry->token        = INVALID_DEFERRED_TOKEN;
+            entry->trigger_time = 0;
+            entry->callback     = NULL;
+            entry->cb_arg       = NULL;
+            return true;
+        }
+    }
+
+    // Not found
+    return false;
+}
+
+void deferred_exec_task(void) {
+    uint32_t now = timer_read32();
+
+    // Throttle only once per millisecond
+    if (((int32_t)TIMER_DIFF_32(now, last_deferred_exec_check)) > 0) {
+        last_deferred_exec_check = now;
+
+        // Run through each of the executors
+        for (int i = 0; i < MAX_DEFERRED_EXECUTORS; ++i) {
+            deferred_executor_t *entry = &executors[i];
+
+            // Check if we're supposed to execute this entry
+            if (entry->token != INVALID_DEFERRED_TOKEN && ((int32_t)TIMER_DIFF_32(entry->trigger_time, now)) <= 0) {
+                // Invoke the callback and work work out if we should be requeued
+                uint32_t delay_ms = entry->callback(entry->trigger_time, entry->cb_arg);
+
+                // Update the trigger time if we have to repeat, otherwise clear it out
+                if (delay_ms > 0) {
+                    // Intentionally add just the delay to the existing trigger time -- this ensures the next
+                    // invocation is with respect to the previous trigger, rather than when it got to execution. Under
+                    // normal circumstances this won't cause issue, but if another executor is invoked that takes a
+                    // considerable length of time, then this ensures best-effort timing between invocations.
+                    entry->trigger_time += delay_ms;
+                } else {
+                    // If it was zero, then the callback is cancelling repeated execution. Free up the slot.
+                    entry->token        = INVALID_DEFERRED_TOKEN;
+                    entry->trigger_time = 0;
+                    entry->callback     = NULL;
+                    entry->cb_arg       = NULL;
+                }
+            }
+        }
+    }
+}

quantum/deferred_exec.h

@@ -0,0 +1,38 @@
+// Copyright 2021 Nick Brassel (@tzarc)
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+#pragma once
+
+#include <stdbool.h>
+#include <stdint.h>
+
+// A token that can be used to cancel an existing deferred execution.
+typedef uint8_t deferred_token;
+#define INVALID_DEFERRED_TOKEN 0
+
+// Callback to execute.
+//  -- Parameter trigger_time: the intended trigger time to execute the callback -- equivalent time-space as timer_read32()
+//               cb_arg: the callback argument specified when enqueueing the deferred executor
+//  -- Return value: Non-zero re-queues the callback to execute after the returned number of milliseconds. Zero cancels repeated execution.
+typedef uint32_t (*deferred_exec_callback)(uint32_t trigger_time, void *cb_arg);
+
+// Configures the supplied deferred executor to be executed after the required number of milliseconds.
+//  -- Parameter delay_ms: the number of milliseconds before executing the callback
+//  --           callback: the executor to invoke
+//  --           cb_arg: the argument to pass to the executor, may be NULL if unused by the executor
+//  -- Return value: a token usable for cancellation, or INVALID_DEFERRED_TOKEN if an error occurred
+deferred_token defer_exec(uint32_t delay_ms, deferred_exec_callback callback, void *cb_arg);
+
+// Allows for extending the timeframe before an existing deferred execution is invoked.
+//  -- Parameter token: the returned value from defer_exec for the deferred execution you wish to extend.
+//  --           delay_ms: the new delay (with respect to the current time)
+//  -- Return value: if the token was found, and the delay was extended
+bool extend_deferred_exec(deferred_token token, uint32_t delay_ms);
+
+// Allows for cancellation of an existing deferred execution.
+//  -- Parameter token: the returned value from defer_exec for the deferred execution you wish to cancel.
+//  -- Return value: if the token was found, and the executor was cancelled
+bool cancel_deferred_exec(deferred_token token);
+
+// Forward declaration for the main loop in order to execute any deferred executors. Should not be invoked by keyboard/user code.
+void deferred_exec_task(void);

quantum/main.c

@@ -43,6 +43,10 @@ void protocol_task(void) {
     protocol_post_task();
 }
 
+#ifdef DEFERRED_EXEC_ENABLE
+void deferred_exec_task(void);
+#endif  // DEFERRED_EXEC_ENABLE
+
 /** \brief Main
  *
  * FIXME: Needs doc
@@ -58,6 +62,12 @@ int main(void) {
     /* Main loop */
     while (true) {
         protocol_task();
+
+#ifdef DEFERRED_EXEC_ENABLE
+        // Run deferred executions
+        deferred_exec_task();
+#endif  // DEFERRED_EXEC_ENABLE
+
         housekeeping_task();
     }
 }

quantum/quantum.h

@@ -54,6 +54,10 @@
 #include <stddef.h>
 #include <stdlib.h>
 
+#ifdef DEFERRED_EXEC_ENABLE
+#    include "deferred_exec.h"
+#endif
+
 extern layer_state_t default_layer_state;
 
 #ifndef NO_ACTION_LAYER

tmk_core/protocol/arm_atsam/main_arm_atsam.c

@@ -40,6 +40,10 @@ void    send_mouse(report_mouse_t *report);
 void    send_system(uint16_t data);
 void    send_consumer(uint16_t data);
 
+#ifdef DEFERRED_EXEC_ENABLE
+void deferred_exec_task(void);
+#endif  // DEFERRED_EXEC_ENABLE
+
 host_driver_t arm_atsam_driver = {keyboard_leds, send_keyboard, send_mouse, send_system, send_consumer};
 
 uint8_t led_states;
@@ -360,6 +364,11 @@ int main(void) {
         }
 #endif  // CONSOLE_ENABLE
 
+#ifdef DEFERRED_EXEC_ENABLE
+        // Run deferred executions
+        deferred_exec_task();
+#endif  // DEFERRED_EXEC_ENABLE
+
         // Run housekeeping
         housekeeping_task();
     }