1
0
Fork 0

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>
This commit is contained in:
Nick Brassel 2021-11-16 05:21:09 +11:00 committed by GitHub
parent b3ee124da6
commit 36d123e9c5
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
9 changed files with 286 additions and 0 deletions

View file

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

View file

@ -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

View file

@ -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
```

View file

@ -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.

152
quantum/deferred_exec.c Normal file
View file

@ -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;
}
}
}
}
}

38
quantum/deferred_exec.h Normal file
View file

@ -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);

View file

@ -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();
}
}

View file

@ -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

View file

@ -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();
}