PQRST  1.2
Priority Queue for Running Simple Tasks
Classes | Macros | Typedefs | Variables
pqrst.h File Reference
#include <inttypes.h>
Include dependency graph for pqrst.h:
This graph shows which files directly or indirectly include this file:

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

Macro Definition Documentation

◆ DOXYGEN_INCLUDE

#define DOXYGEN_INCLUDE   0

◆ MS_FMT

#define MS_FMT   "%u"

A printf format specifier which provides the correct spec for a value of type ms_t.

◆ PQRST_SELF_QUEUE

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

◆ PQRST_TASK_IDENT

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

◆ PQRST_TASK_PRIORITIES

#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)

◆ PQRST_WITH_SLEEPER

#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 Documentation

◆ ms_t

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.

◆ run_task_t

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().

Parameters
thereference time

◆ traverse_queue_cb_t

typedef void(* traverse_queue_cb_t) (ms_t due, const char *ident, const Task *T)

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.

Parameters
duethe current time
identthe identification string of the task
Tthe task

Variable Documentation

◆ Queue

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

const ms_t TIME_NEVER = (ms_t)0xffffffff

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.