PQRST
1.2
Priority Queue for Running Simple Tasks
|
#include <inttypes.h>
Go to the source code of this file.
Classes | |
class | Task |
A Task represents a block of code to be executed at some point in the future. More... | |
class | MaintenanceTask |
There are a few ‘maintenance tasks’ on the queue, placed there by the queueing system. More... | |
class | LoopTask |
A Task which will automatically reschedule itself after it is run. More... | |
class | FunctionTask |
A task which runs a supplied function at a given time. More... | |
class | SleeperTask |
A sleeper task is one which will run only when a given condition is true. More... | |
class | TaskQueue |
A priority queue of Tasks. More... | |
Macros | |
#define | DOXYGEN_INCLUDE 0 |
#define | PQRST_SELF_QUEUE |
If PQRST_SELF_QUEUE is set non-zero, then each Task must be associated with a TaskQueue when it is created; if not, then the library declares a global queue, called Queue , which all tasks are scheduled on, and which must be defined by the calling program. More... | |
#define | PQRST_TASK_PRIORITIES |
If PQRST_TASK_PRIORITIES is set non-zero, then each task has a priority (currently only 0 or 1) which allows it to pre-empt a lower-priority task which might still be running when the high-priority task is due (see the Task::set_priority method for more discussion). More... | |
#define | PQRST_TASK_IDENT |
If PQRST_TASK_IDENT is set non-zero, then each Task object has an identification string which can be set with Task::set_task_ident and retrieved with Task::get_task_ident, and which will be reported at various places if DEBUG is true. More... | |
#define | PQRST_WITH_SLEEPER 0 |
If PQRST_WITH_SLEEPER is set non-zero, then it is possible to register a SleeperTask with the main loop using TaskQueue::add_sleeper. More... | |
#define | MS_FMT "%u" |
A printf format specifier which provides the correct spec for a value of type ms_t. More... | |
Typedefs | |
typedef uint32_t | ms_t |
The Arduino supports a time type of unsigned long , which is a 4-byte unsigned integer on that platform. More... | |
typedef void(* | run_task_t) (ms_t t) |
The type of the function which can be supplied to a FunctionTask. More... | |
typedef void(* | traverse_queue_cb_t) (ms_t due, const char *ident, const Task *T) |
The type of the callback for TaskQueue::traverse_queue. More... | |
Variables | |
const ms_t | TIME_NEVER = (ms_t)0xffffffff |
TIME_NEVER is a time which will never happen. More... | |
TaskQueue | Queue |
The global TaskQueue. More... | |
#define DOXYGEN_INCLUDE 0 |
#define MS_FMT "%u" |
A printf format specifier which provides the correct spec for a value of type ms_t.
#define PQRST_SELF_QUEUE |
#define PQRST_TASK_IDENT |
If PQRST_TASK_IDENT
is set non-zero, then each Task object has an identification string which can be set with Task::set_task_ident and retrieved with Task::get_task_ident, and which will be reported at various places if DEBUG
is true.
See also TaskQueue::traverse_queue, the callback for which changes its signature in this case.
#define PQRST_TASK_PRIORITIES |
If PQRST_TASK_PRIORITIES
is set non-zero, then each task has a priority (currently only 0 or 1) which allows it to pre-empt a lower-priority task which might still be running when the high-priority task is due (see the Task::set_priority method for more discussion).
The default is for this to be zero. If you do need this functionality, then you can set PQRST_TASK_PRIORITIES
to one, at the cost of a few clock cycles.
(The priority
in this module's name refers to the time priorities of the task queue, as distinct from these task priorities)
#define PQRST_WITH_SLEEPER 0 |
If PQRST_WITH_SLEEPER
is set non-zero, then it is possible to register a SleeperTask with the main loop using TaskQueue::add_sleeper.
If this task indicates that it should be woken at any point, then it is immediately scheduled.
typedef uint32_t ms_t |
The Arduino supports a time type of unsigned long
, which is a 4-byte unsigned integer on that platform.
We stick with that size here, for convenience, and refer to it as ms_t
. Note that, although this is referred to as ‘milliseconds’ here and elsewhere in this documentation, this can in practice be any 32-bit time value: millis()
or micros()
or any other jiffies that may be convenient, as long as the times given to the various push/run methods, and as long as the time given to TaskQueue::run_ready are in consistent units.
typedef void(* run_task_t) (ms_t t) |
The type of the function which can be supplied to a FunctionTask.
When the task is ready, the function is called with the current reference time as argument – the function should typically not call millis()
or micros()
.
the | reference time |
The type of the callback for TaskQueue::traverse_queue.
If PQRST_TASK_IDENT
is false, then this has two arguments, giving the due time and a pointer to the Task; if the define is true, then it has three arguments, where the second is the task identifier.The type of the callback passed to the TaskQueue::traverse_queue method. This is called once for each task in the queue.
due | the current time |
ident | the identification string of the task |
T | the task |
TaskQueue Queue |
The global TaskQueue.
If PQRST_SELF_QUEUE
is not defined, then this is declared within the pqrst library, and is globally visible as an extern
.
TIME_NEVER
is a time which will never happen.
Well, actually, to be precise, this will happen at a time value of 0xffffffff
, immediately before the time value wraps around (recall that this number of milliseconds is 49.7 days, and this number of microseconds is 71.6 minutes), but this value is intended to be used as an occasional return value from various functions, and should not be used to schedule a task to never run.
There is at present no way of scheduling a ‘never run’ task.