A task scheduler for AVR microcontrollers.
NOTE: The scheduler uses the MCU’s Timer2 or Timer0 to implement the scheduling clock, so programs that use the scheduler must be carefully written if they also use that timer for other purposes.
NOTE: If the macro SCHED_USE_TIMER0 is defined, then the scheduler will use Timer0 instead of Timer2. Since the ATtiny has no Timer2, this macro is defined internally when LIBAVR_ATTINY is defined. The same applies to the ATmegaU and LIBAVR_ATMEGA_U.
NOTE: If the macro SCHED_NO_ISR is defined, then the scheduler will be compiled without an TIMER[02]_OVF_vect ISR, which means that external code needs to provide that ISR and ensure that it updates the scheduling clock. The documentation of the variable sched_tick_count_h contains more information about this.
| task_sched.h | A task scheduler for AVR microcontrollers. |
| Configuration Macros | |
| Macros | |
| SCHED_CLOCK_PRESCALE_LOG | The two-logarithm of the CPU clock prescale value of the timer that the scheduler uses to keep track of elapsed time. |
| SCHED_MAX_TASKS | The maximum number of tasks that can be scheduled simultaneously. |
| Timekeeping | |
| Macros | |
| CYCLES_TO_MUSECS | Converts a given number of CPU clock cycles to the duration in microseconds of that many clock cycles at the current clock frequency (given by the F_CPU macro). |
| MUSECS_TO_CYCLES | Converts a duration in microseconds to the number of CPU clock cycles performed during that time at the current clock frequency (given by the F_CPU macro). |
| SCHED_CLOCK_PRESCALE | The CPU clock prescale value of the timer that the scheduler uses to keep track of elapsed time. |
| SCHED_TICK_MUSECS | The duration in microseconds of a scheduler tick. |
| SCHED_TIME_LH | Constructs a sched_time value representing the given duration in smallticks and bigticks. |
| SCHED_TIME_TO_TICKS | Evaluates to the total number of smallticks stored in a given sched_time value. |
| SCHED_TIME_MUSECS | Constructs a sched_time value representing the given duration in microseconds. |
| SCHED_TIME_TO_MUSECS | Evaluates to the duration in microseconds represented by a given sched_time value. |
| SCHED_TIME_MS | Constructs a sched_time value representing the given duration in milliseconds. |
| SCHED_TIME_TO_MS | Evaluates to the duration in milliseconds represented by a given sched_time value. |
| SCHED_TIME_ZERO | A sched_time value representing a zero duration (no time at all). |
| SCHED_TIME_MAX | A sched_time value representing the longest representable duration. |
| SCHED_TIME_MAX_TICKS | The largest number of smallticks storable in a sched_time, including those stored as bigticks. |
| SCHED_TIME_MAX_MUSECS | The longest duration representable by a sched_time, in microseconds. |
| SCHED_TIME_MAX_MS | The longest duration representable by a sched_time, in milliseconds (rounded down). |
| sched_time | Represents either a duration or a scheduler timestamp. |
| Variables | |
| l | The smalltick count field. |
| h | The bigtick count field. |
| Task Control and Status Bytes | |
| Macros | |
| TASK_ST_NUM_MASK | Bit mask for the task instance number in a TCSB (see sched_task). |
| TASK_ST_NUM | Constructs a TCSB value (see sched_task) with the given instance number set (the category number and sleep bit are zero). |
| TASK_ST_GET_NUM | Extracts the instance number from a TCSB value (see sched_task). |
| TASK_ST_SET_NUM | Replaces the instance number in a TCSB value (see sched_task). |
| TASK_ST_CAT_MASK | Bit mask for the task category number in a TCSB (see sched_task). |
| TASK_ST_CAT | Constructs a TCSB value (see sched_task) with the given category number set (the instance number and sleep bit are zero). |
| TASK_ST_GET_CAT | Extracts the category number from a TCSB value (see sched_task). |
| TASK_ST_SET_CAT | Replaces the category number in a TCSB value (see sched_task). |
| TASK_ST_NUM_CAT_MASK | Bit mask for the task instance and category numbers in a TCSB (see sched_task). |
| TASK_ST_GET_SLP | Extracts the sleep bit from a TCSB value (see sched_task). |
| TASK_SLEEP_BIT | Integer value with (only) the TCSB sleep bit (see sched_task) set. |
| TASK_SLEEP_BIT_SET | True if and only if the sleep bit is set in the specified TCSB value (see sched_task). |
| TASK_ST_MAKE | Convenience macro for constructing a complete TSCB value (see sched_task). |
| TASK_ST_GARBAGE | This is a special TCSB value (see sched_task) that marks a task as “garbage” when assigned. |
| Task Records | |
| Variables | |
| sched_catflags | The type of fields containing sets of bit flags that correspond to task categories. |
| Macros | |
| SCHED_CATFLAG | Maps task category numbers to the corresponding bit flags. |
| TASK_ST_GET_CATFLAG | Gets the category number from a TCSB value (see sched_task) as a sched_catflags value. |
| Functions | |
| sched_task_handler | The type of pointers to functions that implement a task handler procedure. |
| sched_task | Represents an instance of a task that can be scheduled for execution. |
| Variables | |
| st | Task control and status byte (TCSB) of the task instance. |
| delay | Execution delay of the task instance. |
| handler | Pointer to the task handler procedure. |
| API Variables | |
| Variables | |
| sched_isr_tcww | This is the ISR-Task Category Wakeup Word (I-TCWW), a variable that contains bit flags representing a set of task categories that should be notified at the start of the next scheduler iteration. |
| sched_task_tcww | This is the Task-Task Category Wakeup Word (T-TCWW), a variable that contains bit flags representing a set of task categories that should be notified at the start of the next scheduler iteration. |
| sched_ticks | The scheduler iteration timestamp. |
| sched_delta | The scheduler iteration time delta. |
| sched_list_size | Current size of the task list. |
| sched_tick_count_h | High bytes (“bigticks”) of the scheduling clock’s tick count. |
| API Functions - Helpers | |
| Functions | |
| sched_time_is_zero | Tests whether a sched_time contains a zero value. |
| sched_time_gt | Tests whether sched_time a contains a greater integer value than b. |
| sched_time_lt | Tests whether sched_time a contains a lesser integer value than b. |
| sched_time_gte | Tests whether sched_time a contains a greater-or-equal integer value than b. |
| sched_time_lte | Tests whether sched_time a contains a lesser-or-equal integer value than b. |
| sched_time_add | Adds sched_time b to sched_time a. |
| sched_time_sub | Subtracts sched_time b from sched_time a. |
| sched_busy_wait | Busy waits a specified duration of time. |
| API Functions - Scheduler Operations | |
| Macros | |
| SCHED_FIND | Deprecated, kept for backward compatibility. |
| Functions | |
| sched_init | Initializes the task scheduler. |
| sched_ptr_query | Queries the task list. |
| sched_query | Queries the task list. |
| sched_find | Queries the task list. |
| sched_invoke | Invokes a matching task on the task list. |
| sched_invoke_all | Invokes all matching tasks on the task list. |
| sched_wake | Awakens and optionally notifies a matching task on the task list. |
| sched_wake_all | Awakens and optionally notifies all matching tasks on the task list. |
| sched_get_at | Accesses the task list by index. |
| sched_add | Adds the specified task to the task list. |
| sched_remove | Marks a matching task on the task list for removal. |
| sched_remove_all | Marks all matching tasks on the task list for removal. |
| sched_get_timestamp | Gets a scheduler timestamp corresponding to the current time. |
| sched_run | Enters the main loop of the task scheduler. |
| Macros | |
| SCHED_CLOCK_PRESCALE_LOG | The two-logarithm of the CPU clock prescale value of the timer that the scheduler uses to keep track of elapsed time. |
| SCHED_MAX_TASKS | The maximum number of tasks that can be scheduled simultaneously. |
The two-logarithm of the CPU clock prescale value of the timer that the scheduler uses to keep track of elapsed time. Either Timer2 or Timer0 is used, depending on whether SCHED_USE_TIMER0 is defined. Configuration macro.
Default value: 6 if SCHED_USE_TIMER0, LIBAVR_ATTINY or LIBAVR_ATMEGA_U is defined, otherwise 5.
CAUTION: When the scheduler uses Timer2, this macro MUST be defined to be 0, 3, 5, 6, 7, 8 or 10. When Timer0 is used, this macro MUST be defined to be 0, 3, 6, 8 or 10. It MUST also be true that:
1 <= (1000000 * (1 << SCHED_CLOCK_PRESCALE_LOG)) / F_CPU <= 255.
CAUTION: This macro SHOULD have a value such that
(1000000 * (1 << SCHED_CLOCK_PRESCALE_LOG)) / F_CPU
is an integer (without integer division). If it isn’t, the scheduler’s timekeeping, including values produced by the time-related macros in this header, will be very inexact. (See SCHED_TICK_MUSECS.)
The maximum number of tasks that can be scheduled simultaneously. The limit applies to the total number of tasks on the task list, including sleeping and garbage tasks. Configuration macro.
Default value: 8 if LIBAVR_ATTINY is defined, otherwise 16.
CAUTION: This value MUST be in the range 1-254.
CAUTION: Increasing this value will increase the amount of statically allocated memory used by the scheduler.
| Macros | |
| CYCLES_TO_MUSECS | Converts a given number of CPU clock cycles to the duration in microseconds of that many clock cycles at the current clock frequency (given by the F_CPU macro). |
| MUSECS_TO_CYCLES | Converts a duration in microseconds to the number of CPU clock cycles performed during that time at the current clock frequency (given by the F_CPU macro). |
| SCHED_CLOCK_PRESCALE | The CPU clock prescale value of the timer that the scheduler uses to keep track of elapsed time. |
| SCHED_TICK_MUSECS | The duration in microseconds of a scheduler tick. |
| SCHED_TIME_LH | Constructs a sched_time value representing the given duration in smallticks and bigticks. |
| SCHED_TIME_TO_TICKS | Evaluates to the total number of smallticks stored in a given sched_time value. |
| SCHED_TIME_MUSECS | Constructs a sched_time value representing the given duration in microseconds. |
| SCHED_TIME_TO_MUSECS | Evaluates to the duration in microseconds represented by a given sched_time value. |
| SCHED_TIME_MS | Constructs a sched_time value representing the given duration in milliseconds. |
| SCHED_TIME_TO_MS | Evaluates to the duration in milliseconds represented by a given sched_time value. |
| SCHED_TIME_ZERO | A sched_time value representing a zero duration (no time at all). |
| SCHED_TIME_MAX | A sched_time value representing the longest representable duration. |
| SCHED_TIME_MAX_TICKS | The largest number of smallticks storable in a sched_time, including those stored as bigticks. |
| SCHED_TIME_MAX_MUSECS | The longest duration representable by a sched_time, in microseconds. |
| SCHED_TIME_MAX_MS | The longest duration representable by a sched_time, in milliseconds (rounded down). |
Converts a given number of CPU clock cycles to the duration in microseconds of that many clock cycles at the current clock frequency (given by the F_CPU macro). Function-like macro.
CAUTION: This macro does 32-bit integer arithmetic that is implemented in software on the MCU (i.e. it will be slow and potentially bloat the compiled program) unless the argument is a compile-time constant.
| N | Number of clock cycles. |
Duration in microseconds of N clock cycles.
Converts a duration in microseconds to the number of CPU clock cycles performed during that time at the current clock frequency (given by the F_CPU macro). Function-like macro.
CAUTION: This macro does 32-bit integer arithmetic that is implemented in software on the MCU (i.e. it will be slow and potentially bloat the compiled program) unless the argument is a compile-time constant.
| T | Time in microseconds. |
Number of clock cycles performed by the MCU in T microseconds.
The CPU clock prescale value of the timer that the scheduler uses to keep track of elapsed time. Equivalent to the number of CPU clock cycles per timer tick. It is usually best to set this via SCHED_CLOCK_PRESCALE_LOG. Constant macro.
The duration in microseconds of a scheduler tick. Constant macro. Depends on SCHED_CLOCK_PRESCALE_LOG and F_CPU. Equal to
(1000000 * (1 << SCHED_CLOCK_PRESCALE_LOG)) / F_CPU // Integer division
Constructs a sched_time value representing the given duration in smallticks and bigticks. Function-like macro.
| L | Unsigned 8-bit smalltick count. |
| H | Unsigned 16-bit bigtick count. |
A sched_time with the smalltick counter set to L and the bigtick counter set to H.
Evaluates to the total number of smallticks stored in a given sched_time value. Converts bigticks to smallticks to obtain the total number. Function-like macro.
| T | A sched_time. |
The number of smallticks (including converted bigticks) stored in T. The type of the result will be uint32_t.
Constructs a sched_time value representing the given duration in microseconds. Function-like macro.
| T | A duration in microseconds. |
A sched_time representing T microseconds.
Evaluates to the duration in microseconds represented by a given sched_time value. Function-like macro.
| T | A sched_time representing a duration. |
The duration represented by T, in microseconds. The type of the result will be uint32_t.
Constructs a sched_time value representing the given duration in milliseconds. Function-like macro.
CAUTION: This macro does 32-bit integer arithmetic that is implemented in software on the MCU (i.e. it will be slow and potentially bloat the compiled program) unless the argument is a compile-time constant.
| T | A duration in milliseconds. |
A sched_time representing T milliseconds.
Evaluates to the duration in milliseconds represented by a given sched_time value. Function-like macro.
| T | A sched_time representing a duration. |
The duration represented by T, in milliseconds (rounded down). The type of the result will be uint32_t.
A sched_time value representing a zero duration (no time at all). Constant macro.
A sched_time value representing the longest representable duration. Constant macro.
The largest number of smallticks storable in a sched_time, including those stored as bigticks. The type of this macro is uint32_t. Constant macro.
The longest duration representable by a sched_time, in microseconds. The type of this macro is uint32_t. Constant macro.
The longest duration representable by a sched_time, in milliseconds (rounded down). The type of this macro is uint32_t. Constant macro.
typedef struct sched_time
Represents either a duration or a scheduler timestamp. Time is measured in scheduler ticks, and the length of a scheduler tick is the reciprocal of the scheduling clock frequency, which depends on the CPU clock frequency and the scheduler’s timer prescaler setting. See SCHED_CLOCK_PRESCALE_LOG and SCHED_TICK_MUSECS.
Each sched_time contains two scheduler tick counts, the “smalltick” count in the 8-bit field l and the “bigtick” count in the 16-bit field h. Together, the two fields represent a duration of
SCHED_TICK_MUSECS*(256*h + l)
microseconds. The maximum representable duration (SCHED_TIME_MAX) is
SCHED_TICK_MUSECS*16777215
microseconds. Since SCHED_TICK_MUSECS must be at least 1, durations up to 16 seconds are always representable.
The scheduler stores the timestamp of the current scheduler iteration in the global variable sched_ticks. A scheduler timestamp encodes the duration of time elapsed since the latest rollover of the scheduling clock’s tick counter, at the time when the timestamp was recorded. This means that a timestamp with a larger total tick count (obtained via SCHED_TIME_TO_TICKS) than another may still represent an earlier point in time.
However, provided that the total duration of scheduler iterations performed between iteration X and subsequent iteration Y does not exceed the maximum representable duration (SCHED_TIME_MAX), the difference (as calculated by sched_time_sub) between a timestamp obtained (from sched_ticks) during iteration Y and one obtained during iteration X will always be equal to the duration of time (as measured by the scheduling clock) between the start of iteration X and the start of iteration Y.
uint8_t l
The smalltick count field. The duration of one smalltick (which is also the resolution of the scheduling clock) is SCHED_TICK_MUSECS microseconds.
| Macros | |
| TASK_ST_NUM_MASK | Bit mask for the task instance number in a TCSB (see sched_task). |
| TASK_ST_NUM | Constructs a TCSB value (see sched_task) with the given instance number set (the category number and sleep bit are zero). |
| TASK_ST_GET_NUM | Extracts the instance number from a TCSB value (see sched_task). |
| TASK_ST_SET_NUM | Replaces the instance number in a TCSB value (see sched_task). |
| TASK_ST_CAT_MASK | Bit mask for the task category number in a TCSB (see sched_task). |
| TASK_ST_CAT | Constructs a TCSB value (see sched_task) with the given category number set (the instance number and sleep bit are zero). |
| TASK_ST_GET_CAT | Extracts the category number from a TCSB value (see sched_task). |
| TASK_ST_SET_CAT | Replaces the category number in a TCSB value (see sched_task). |
| TASK_ST_NUM_CAT_MASK | Bit mask for the task instance and category numbers in a TCSB (see sched_task). |
| TASK_ST_GET_SLP | Extracts the sleep bit from a TCSB value (see sched_task). |
| TASK_SLEEP_BIT | Integer value with (only) the TCSB sleep bit (see sched_task) set. |
| TASK_SLEEP_BIT_SET | True if and only if the sleep bit is set in the specified TCSB value (see sched_task). |
| TASK_ST_MAKE | Convenience macro for constructing a complete TSCB value (see sched_task). |
| TASK_ST_GARBAGE | This is a special TCSB value (see sched_task) that marks a task as “garbage” when assigned. |
Bit mask for the task instance number in a TCSB (see sched_task). Constant macro. Useful for task list queries (see sched_query).
Constructs a TCSB value (see sched_task) with the given instance number set (the category number and sleep bit are zero). Function-like macro.
| NUM | Task instance number in the range 0-7. |
A TCSB value with (only) the instance number NUM set.
Extracts the instance number from a TCSB value (see sched_task). Function-like macro.
| ST | The TCSB value to get the instance number from. |
The instance number from ST, right-shifted into the three least significant bits.
Replaces the instance number in a TCSB value (see sched_task). Function-like macro.
| ST | The TCSB value to replace the instance number in. |
| NUM | Task instance number in the range 0-7. |
A TCSB value with the category number and sleep bit equal to the ones in ST and the instance number set to NUM.
Bit mask for the task category number in a TCSB (see sched_task). Constant macro. Useful for task list queries (see sched_query).
Constructs a TCSB value (see sched_task) with the given category number set (the instance number and sleep bit are zero). Function-like macro.
| CAT | Task category number in the range 0-15. |
A TCSB value with (only) the category number CAT set.
Extracts the category number from a TCSB value (see sched_task). Function-like macro.
| ST | The TCSB value to get the category number from. |
The category number from ST, right-shifted into the four least significant bits.
Replaces the category number in a TCSB value (see sched_task). Function-like macro.
| ST | The TCSB value to replace the category number in. |
| CAT | Task category number in the range 0-15. |
A TCSB value with the instance number and sleep bit equal to the ones in ST and the category number set to CAT.
Bit mask for the task instance and category numbers in a TCSB (see sched_task). Constant macro. Useful for task list queries (see sched_query).
// Get pointer to task instance 2 in category 5. sched_task *task_p = SCHED_FIND( TASK_ST_NUM_CAT_MASK, TASK_ST_NUM(2) | TASK_ST_CAT(5), 0); // Invoke task instance 4 in category 11, more tersely. sched_invoke(TASK_ST_NUM_CAT_MASK, TASK_ST_MAKE(4, 11, 0), 0);
Extracts the sleep bit from a TCSB value (see sched_task). Function-like macro.
NOTE: When only the truth value of the result matters, TASK_SLEEP_BIT_SET can be a faster alternative.
| ST | The TCSB value to get the sleep bit from. |
The sleep bit from ST, right-shifted into the least significant bit.
Integer value with (only) the TCSB sleep bit (see sched_task) set. Constant macro. Can be used to put a task to sleep or awaken it:
task->st |= TASK_SLEEP_BIT; // Sleep now. task->st &= ~TASK_SLEEP_BIT; // Awaken!
True if and only if the sleep bit is set in the specified TCSB value (see sched_task). Function-like macro.
NOTE: This macro can be faster than TASK_ST_GET_SLP, especially if the argument is not a compile-time constant.
| ST | The TCSB value to check the sleep bit in. |
An integer value that is true (i.e. non-zero) if and only if the sleep bit in ST is set to one (1). This value is NOT necessarily either 0 or 1.
Convenience macro for constructing a complete TSCB value (see sched_task). Function-like macro.
| N | Task instance number in the range 0-7. |
| C | Task category number in the range 0-15. |
| S | Task sleep bit, 0 or 1. |
A TCSB value with the instance number set to N, the category number set to C and the sleep bit set to S.
This is a special TCSB value (see sched_task) that marks a task as “garbage” when assigned. At the start of each scheduler iteration, the scheduler will remove all tasks marked as garbage from the task list. Constant macro.
task->st = TASK_ST_GARBAGE; // This is garbage, throw it out.
| Variables | |
| sched_catflags | The type of fields containing sets of bit flags that correspond to task categories. |
| Macros | |
| SCHED_CATFLAG | Maps task category numbers to the corresponding bit flags. |
| TASK_ST_GET_CATFLAG | Gets the category number from a TCSB value (see sched_task) as a sched_catflags value. |
| Functions | |
| sched_task_handler | The type of pointers to functions that implement a task handler procedure. |
Maps task category numbers to the corresponding bit flags. Function-like macro.
| N | A task category number in the range 0-15. |
A sched_catflags value with (only) bit number N set to one (1).
Gets the category number from a TCSB value (see sched_task) as a sched_catflags value. Function-like macro.
| ST | The TCSB value to get the category bit flag for. |
A sched_catflags value with (only) the bit corresponding to the category number in ST set to one (1).
typedef void ( * sched_task_handler )(struct sched_task *task)
The type of pointers to functions that implement a task handler procedure.
| task | Pointer to the sched_task struct of the task instance. |
uint8_t st
Task control and status byte (TCSB) of the task instance. The control and status byte has the following format:
7 6 5 4 3 2 1 0 | SLP | CAT3 | CAT2 | CAT1 | CAT0 | NUM2 | NUM1 | NUM0 |
| NUM2:0 | Task instance number, in the range 0-7. |
| CAT3:0 | Task category number, in the range 0-15. |
| SLP | Sleep bit. If this is set to one, the task will not be executed until a wakeup event occurs. |
NOTE: TCSB values can be conveniently constructed with the macro TASK_ST_MAKE.
CAUTION: A task where the TCSB is set to all ones will be treated as garbage by the scheduler, which means that it will be removed from the task list at the start of a scheduler iteration. For this reason, assigning instance number 7 to a task in category 15 is generally something to be avoided (since putting such a task to sleep is equivalent to marking it as garbage). Also note that any task marked as garbage will effectively be in category 15, which can be confusing if that category is also used for non-garbage tasks. (See TASK_ST_GARBAGE.)
sched_time delay
Execution delay of the task instance. The scheduler will subtract elapsed time deltas (i.e. the durations of scheduler iterations) from this field, and will execute the task when the value of the field reaches zero. If the current time delta is greater than the value of the field, the field will be set to zero.
NOTE: When the scheduler invokes a task’s handler for any reason, including the task being notified or invoked via sched_invoke, any currently elapsing delay is canceled. The delay field always starts out zeroed when the task handler is invoked.
NOTE: If a task should execute periodically, its task handler should re-assign the desired period to the delay field upon task execution. The scheduler itself will simply leave zeroed delay fields unchanged and execute the corresponding tasks once per scheduler iteration.
sched_task_handler handler
Pointer to the task handler procedure. The task handler will be invoked whenever the scheduler executes the task. The handler may also be invoked via the API functions sched_invoke and sched_invoke_all.
NOTE: It is perfectly safe to update this field while the scheduler is running (except in ISRs). For example, handler field updates can be used to implement a state machine in a task.
| Variables | |
| sched_isr_tcww | This is the ISR-Task Category Wakeup Word (I-TCWW), a variable that contains bit flags representing a set of task categories that should be notified at the start of the next scheduler iteration. |
| sched_task_tcww | This is the Task-Task Category Wakeup Word (T-TCWW), a variable that contains bit flags representing a set of task categories that should be notified at the start of the next scheduler iteration. |
| sched_ticks | The scheduler iteration timestamp. |
| sched_delta | The scheduler iteration time delta. |
| sched_list_size | Current size of the task list. |
| sched_tick_count_h | High bytes (“bigticks”) of the scheduling clock’s tick count. |
extern volatile sched_catflags sched_isr_tcww
This is the ISR-Task Category Wakeup Word (I-TCWW), a variable that contains bit flags representing a set of task categories that should be notified at the start of the next scheduler iteration.
The I-TCWW is a volatile variable and should be used by ISRs that need to notify categories of tasks.
extern sched_catflags sched_task_tcww
This is the Task-Task Category Wakeup Word (T-TCWW), a variable that contains bit flags representing a set of task categories that should be notified at the start of the next scheduler iteration.
The T-TCWW is a non-volatile variable and should be used by task handler procedures that need to notify categories of tasks.
extern sched_time sched_ticks
The scheduler iteration timestamp. When task handlers run, this variable will contain a timestamp obtained at the beginning of the current scheduler iteration.
NOTE: The function sched_get_timestamp can provide timestamps that are closer to the current time, in case high precision is needed.
extern volatile uint16_t sched_tick_count_h
High bytes (“bigticks”) of the scheduling clock’s tick count.
NOTE: To get correct scheduling when SCHED_NO_ISR is defined, this variable MUST be incremented in an externally defined TIMER2_OVF_vect (TIMER0_OVF_vect when SCHED_USE_TIMER0 is defined) ISR.
| Functions | |
| sched_time_is_zero | Tests whether a sched_time contains a zero value. |
| sched_time_gt | Tests whether sched_time a contains a greater integer value than b. |
| sched_time_lt | Tests whether sched_time a contains a lesser integer value than b. |
| sched_time_gte | Tests whether sched_time a contains a greater-or-equal integer value than b. |
| sched_time_lte | Tests whether sched_time a contains a lesser-or-equal integer value than b. |
| sched_time_add | Adds sched_time b to sched_time a. |
| sched_time_sub | Subtracts sched_time b from sched_time a. |
| sched_busy_wait | Busy waits a specified duration of time. |
uint8_t sched_time_is_zero( sched_time t )
Tests whether a sched_time contains a zero value. The test is equivalent to the expression t.l == 0 && t.h == 0.
uint8_t sched_time_gt( sched_time a, sched_time b )
Tests whether sched_time a contains a greater integer value than b. The test is equivalent to the expression a.h+a.l > b.h+b.l.
NOTE: This operation is only meaningful for durations. It CANNOT be used to determine whether one scheduler timestamp represents a later moment in time than another.
uint8_t sched_time_lt( sched_time a, sched_time b )
Tests whether sched_time a contains a lesser integer value than b. The test is equivalent to the expression a.h+a.l < b.h+b.l.
NOTE: This operation is only meaningful for durations. It CANNOT be used to determine whether one scheduler timestamp represents an earlier moment in time than another.
uint8_t sched_time_gte( sched_time a, sched_time b )
Tests whether sched_time a contains a greater-or-equal integer value than b. The test is equivalent to the expression a.h+a.l >= b.h+b.l.
NOTE: This operation is only meaningful for durations. It CANNOT be used to determine whether one scheduler timestamp represents a later moment in time than another.
uint8_t sched_time_lte( sched_time a, sched_time b )
Tests whether sched_time a contains a lesser-or-equal integer value than b. The test is equivalent to the expression a.h+a.l <= b.h+b.l.
NOTE: This operation is only meaningful for durations. It CANNOT be used to determine whether one scheduler timestamp represents an earlier moment in time than another.
sched_time sched_time_add( sched_time a, sched_time b )
Adds sched_time b to sched_time a. The addition is performed in a way that is equivalent to addition of 24-bit unsigned smalltick counts (with wraparound in case the sum is greater than SCHED_TIME_MAX).
This operation produces a meaningful result when one duration is added to another such that their sum is no longer than SCHED_TIME_MAX. In that case, the result represents a nonnegative duration.
This operation also produces a meaningful result when a duration is added to a timestamp. In that case, the result is the timestamp of the point in time that many seconds later than the one the original timestamp corresponds to.
sched_time sched_time_sub( sched_time a, sched_time b )
Subtracts sched_time b from sched_time a. The subtraction is performed in a way that is equivalent to subtraction of 24-bit unsigned smalltick counts (with wraparound in case a is less than b).
This operation produces a meaningful result when one duration is subtracted from another that is no shorter and when one timestamp is subtracted from another that was obtained no earlier in time, and not more than SCHED_TIME_MAX seconds later. In those cases, the result represents a nonnegative duration.
This operation also produces a meaningful result when a duration is subtracted from a timestamp. In that case, the result is the timestamp of the point in time that many seconds earlier than the one the original timestamp corresponds to.
void sched_busy_wait( sched_time duration )
Busy waits a specified duration of time. The whole range of durations representable by sched_time is supported, accurate down to four CPU clock cycles (plus a small overhead).
| duration | A sched_time representing the requested duration of the busy wait. |
| Macros | |
| SCHED_FIND | Deprecated, kept for backward compatibility. |
| Functions | |
| sched_init | Initializes the task scheduler. |
| sched_ptr_query | Queries the task list. |
| sched_query | Queries the task list. |
| sched_find | Queries the task list. |
| sched_invoke | Invokes a matching task on the task list. |
| sched_invoke_all | Invokes all matching tasks on the task list. |
| sched_wake | Awakens and optionally notifies a matching task on the task list. |
| sched_wake_all | Awakens and optionally notifies all matching tasks on the task list. |
| sched_get_at | Accesses the task list by index. |
| sched_add | Adds the specified task to the task list. |
| sched_remove | Marks a matching task on the task list for removal. |
| sched_remove_all | Marks all matching tasks on the task list for removal. |
| sched_get_timestamp | Gets a scheduler timestamp corresponding to the current time. |
| sched_run | Enters the main loop of the task scheduler. |
Deprecated, kept for backward compatibility. Use the function sched_find instead of this macro.
sched_task *sched_ptr_query( uint8_t st_mask, uint8_t st_val, uint8_t start_i, uint8_t * task_i_p )
Queries the task list. Returns a pointer to the first encountered task on the list for which the TCSB bits selected (i.e. set to one) in st_mask are equal to the corresponding bits in st_val. The search starts at index start_i in the task list. If no matching task is found, then a null pointer is returned. If a matching task is found, then the task list index of that task is stored in the location pointed to by task_i_p.
NOTE: If all bits in st_mask are set (i.e. the value is 255) and st_val is TASK_ST_GARBAGE, then a null pointer will always be returned. This special case can be used when an always-empty query is useful, e.g. when some API requires task query arguments to use as a filter for synchronous task invocation, but that feature isn’t being used.
NOTE: The matched task may be one that is marked as garbage.
| st_mask | Bit mask to apply to the task control and status byte. |
| st_val | Bit pattern to compare with the task control and status byte. |
| start_i | Starting index of the forward search of the task list. |
| task_i_p | Pointer to location where the task list index of the matched task should be stored. Note that this location is NOT updated if no matching task is found. |
A pointer to the matched task, or a null pointer if there are no matching tasks.
uint8_t sched_query( uint8_t st_mask, uint8_t st_val, uint8_t start_i )
Queries the task list. Returns the task list index of the first encountered task on the list for which the TCSB bits selected (i.e. set to one) in st_mask are equal to the corresponding bits in st_val. The search starts at index start_i in the task list. If no matching task is found, then SCHED_MAX_TASKS is returned.
NOTE: This function delegates to sched_ptr_query, and the notes for that function also apply to this one.
| st_mask | Bit mask to apply to the task control and status byte. |
| st_val | Bit pattern to compare with the task control and status byte. |
| start_i | Starting index of the forward search of the task list. |
The task list index of the matched task, or SCHED_MAX_TASKS if there are no matching tasks.
sched_task *sched_find( uint8_t st_mask, uint8_t st_val, uint8_t start_i )
Queries the task list. Returns a pointer to the first encountered task on the list for which the TCSB bits selected (i.e. set to one) in st_mask are equal to the corresponding bits in st_val. The search starts at index start_i in the task list. If no matching task is found, then a null pointer is returned.
NOTE: This function delegates to sched_ptr_query, and the notes for that function also apply to this one.
| st_mask | Bit mask to apply to the task control and status byte. |
| st_val | Bit pattern to compare with the task control and status byte. |
| start_i | Starting index of the forward search of the task list. |
A pointer to the matched task, or a null pointer if there are no matching tasks.
uint8_t sched_invoke( uint8_t st_mask, uint8_t st_val, uint8_t start_i )
Invokes a matching task on the task list. Invokes and returns the task list index of the first encountered task on the list for which the TCSB bits selected (i.e. set to one) in st_mask are equal to the corresponding bits in st_val. The search starts at index start_i in the task list. If no matching task is found, then SCHED_MAX_TASKS is returned.
NOTE: Before handler invocation, sleeping tasks are awakened (i.e. have the sleep bit in their TCSB cleared) and elapsing execution delays canceled.
NOTE: A matched task marked as garbage is NOT invoked or awakened, but the index where the task was found is still returned.
NOTE: The task handler procedure is invoked synchronously.
NOTE: This function delegates to sched_ptr_query, and the notes for that function also apply to this one.
| st_mask | Bit mask to apply to the task control and status byte. |
| st_val | Bit pattern to compare with the task control and status byte. |
| start_i | Starting index of the forward search of the task list. |
The task list index of the matched task, or SCHED_MAX_TASKS if there are no matching tasks.
void sched_invoke_all( uint8_t st_mask, uint8_t st_val )
Invokes all matching tasks on the task list. Invokes every non-garbage task on the list for which the TCSB bits selected (i.e. set to one) in st_mask are equal to the corresponding bits in st_val.
NOTE: This function delegates to sched_invoke, and the notes for that function also apply to this one.
| st_mask | Bit mask to apply to the task control and status byte. |
| st_val | Bit pattern to compare with the task control and status byte. |
uint8_t sched_wake( uint8_t st_mask, uint8_t st_val, uint8_t start_i, uint8_t notify )
Awakens and optionally notifies a matching task on the task list. Awakens and returns the task list index of the first encountered task on the list for which the TCSB bits selected (i.e. set to one) in st_mask are equal to the corresponding bits in st_val. The search starts at index start_i in the task list. If no matching task is found, then SCHED_MAX_TASKS is returned.
NOTE: A matched task marked as garbage is NOT awakened, but the index where the task was found is still returned.
NOTE: This function delegates to sched_ptr_query, and the notes for that function also apply to this one.
| st_mask | Bit mask to apply to the task control and status byte. |
| st_val | Bit pattern to compare with the task control and status byte. |
| start_i | Starting index of the forward search of the task list. |
| notify | If this is true, a matched task will be notified (i.e. have its execution delay set to zero) instead of just awakened. |
The task list index of the matched task, or SCHED_MAX_TASKS if there are no matching tasks.
void sched_wake_all( uint8_t st_mask, uint8_t st_val, uint8_t notify )
Awakens and optionally notifies all matching tasks on the task list. Awakens every non-garbage task on the list for which the TCSB bits selected (i.e. set to one) in st_mask are equal to the corresponding bits in st_val.
NOTE: This function delegates to sched_wake, and the notes for that function also apply to this one.
| st_mask | Bit mask to apply to the task control and status byte. |
| st_val | Bit pattern to compare with the task control and status byte. |
| notify | If this is true, matched tasks will be notified (i.e. have their execution delay set to zero) instead of just awakened. |
uint8_t sched_add( const sched_task * task )
Adds the specified task to the task list.
| task | Pointer to the task to add to the task list. The specified sched_task structure will be copied into internal storage. |
The task list index of the added task, or SCHED_MAX_TASKS if the task couldn’t be added.
uint8_t sched_remove( uint8_t st_mask, uint8_t st_val, uint8_t start_i )
Marks a matching task on the task list for removal. Marks as garbage and returns the index of the first encountered task on the list for which the TCSB bits selected (i.e. set to one) in st_mask are equal to the corresponding bits in st_val. The search starts at index start_i in the task list. If no matching task is found, then SCHED_MAX_TASKS is returned.
NOTE: This function does not check whether the matching task was already marked as garbage.
NOTE: This function delegates to sched_ptr_query, and the notes for that function also apply to this one.
| st_mask | Bit mask to apply to the task control and status byte. |
| st_val | Bit pattern to compare with the task control and status byte. |
| start_i | Starting index of the forward search of the task list. |
The task list index of the task marked for removal, or SCHED_MAX_TASKS if there were no matching tasks.
void sched_remove_all( uint8_t st_mask, uint8_t st_val )
Marks all matching tasks on the task list for removal. Marks as garbage every task on the list for which the TCSB bits selected (i.e. set to one) in st_mask are equal to the corresponding bits in st_val.
NOTE: This function delegates to sched_remove, and the notes for that function also apply to this one.
| st_mask | Bit mask to apply to the task control and status byte. |
| st_val | Bit pattern to compare with the task control and status byte. |
sched_time sched_get_timestamp( void )
Gets a scheduler timestamp corresponding to the current time.
NOTE: This function can provide a timestamp that corresponds more closely to the current time than the scheduler iteration timestamp in sched_ticks does, but calling the function is less efficient than reading the variable.
CAUTION: This function MUST NOT be called before the scheduler has been started (via sched_run), or ever from an ISR.
A sched_time containing the scheduler timestamp for the current time.
Represents either a duration or a scheduler timestamp.
typedef struct sched_time
The smalltick count field.
uint8_t l
The bigtick count field.
uint16_t h
Represents an instance of a task that can be scheduled for execution.
typedef struct sched_task
The type of fields containing sets of bit flags that correspond to task categories.
typedef uint16_t sched_catflags
The type of pointers to functions that implement a task handler procedure.
typedef void ( * sched_task_handler )(struct sched_task *task)
Task control and status byte (TCSB) of the task instance.
uint8_t st
Execution delay of the task instance.
sched_time delay
Pointer to the task handler procedure.
sched_task_handler handler
This is the ISR-Task Category Wakeup Word (I-TCWW), a variable that contains bit flags representing a set of task categories that should be notified at the start of the next scheduler iteration.
extern volatile sched_catflags sched_isr_tcww
This is the Task-Task Category Wakeup Word (T-TCWW), a variable that contains bit flags representing a set of task categories that should be notified at the start of the next scheduler iteration.
extern sched_catflags sched_task_tcww
The scheduler iteration timestamp.
extern sched_time sched_ticks
The scheduler iteration time delta.
extern sched_time sched_delta
Current size of the task list.
extern uint8_t sched_list_size
High bytes (“bigticks”) of the scheduling clock’s tick count.
extern volatile uint16_t sched_tick_count_h
Tests whether a sched_time contains a zero value.
uint8_t sched_time_is_zero( sched_time t )
Tests whether sched_time a contains a greater integer value than b.
uint8_t sched_time_gt( sched_time a, sched_time b )
Tests whether sched_time a contains a lesser integer value than b.
uint8_t sched_time_lt( sched_time a, sched_time b )
Tests whether sched_time a contains a greater-or-equal integer value than b.
uint8_t sched_time_gte( sched_time a, sched_time b )
Tests whether sched_time a contains a lesser-or-equal integer value than b.
uint8_t sched_time_lte( sched_time a, sched_time b )
Adds sched_time b to sched_time a.
sched_time sched_time_add( sched_time a, sched_time b )
Subtracts sched_time b from sched_time a.
sched_time sched_time_sub( sched_time a, sched_time b )
Busy waits a specified duration of time.
void sched_busy_wait( sched_time duration )
Initializes the task scheduler.
void sched_init( void )
Queries the task list.
sched_task *sched_ptr_query( uint8_t st_mask, uint8_t st_val, uint8_t start_i, uint8_t * task_i_p )
Queries the task list.
uint8_t sched_query( uint8_t st_mask, uint8_t st_val, uint8_t start_i )
Queries the task list.
sched_task *sched_find( uint8_t st_mask, uint8_t st_val, uint8_t start_i )
Invokes a matching task on the task list.
uint8_t sched_invoke( uint8_t st_mask, uint8_t st_val, uint8_t start_i )
Invokes all matching tasks on the task list.
void sched_invoke_all( uint8_t st_mask, uint8_t st_val )
Awakens and optionally notifies a matching task on the task list.
uint8_t sched_wake( uint8_t st_mask, uint8_t st_val, uint8_t start_i, uint8_t notify )
Awakens and optionally notifies all matching tasks on the task list.
void sched_wake_all( uint8_t st_mask, uint8_t st_val, uint8_t notify )
Accesses the task list by index.
sched_task *sched_get_at( uint8_t i )
Adds the specified task to the task list.
uint8_t sched_add( const sched_task * task )
Marks a matching task on the task list for removal.
uint8_t sched_remove( uint8_t st_mask, uint8_t st_val, uint8_t start_i )
Marks all matching tasks on the task list for removal.
void sched_remove_all( uint8_t st_mask, uint8_t st_val )
Gets a scheduler timestamp corresponding to the current time.
sched_time sched_get_timestamp( void )
Enters the main loop of the task scheduler.
void sched_run( void ) __attribute__ ((noreturn))