File espos_sched.h¶

FileList > espos_flow > include > espos_sched.h

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "esp_err.h"

Classes¶

Type	Name
struct	espos_sched_t
struct	espos_sched_timer_t

Public Types¶

Type	Name
typedef void(*	espos_sched_cb_t
typedef uint32_t	espos_sched_handle_t

Public Functions¶

Type	Name
esp_err_t	espos_sched_add (espos_sched_t * s, uint32_t now_ms, uint32_t delay_ms, uint32_t period_ms, espos_sched_cb_t cb, void * arg, espos_sched_handle_t * out) Schedule `cb` to run`delay_ms` after`now_ms` , then every`period_ms` (0 = one-shot).
esp_err_t	espos_sched_cancel (espos_sched_t * s, espos_sched_handle_t h) Cancel a timer.
size_t	espos_sched_count (const espos_sched_t * s) Live timers (added, not yet cancelled or fired-and-done).
size_t	espos_sched_fire (espos_sched_t * s, uint32_t now_ms) Run every timer due at `now_ms` and return how many fired.
esp_err_t	espos_sched_init (espos_sched_t * s, espos_sched_timer_t * slots, size_t cap) Bind a scheduler to a caller-owned array of `cap` slots.
uint32_t	espos_sched_next_due (const espos_sched_t * s, uint32_t now_ms) Milliseconds until the earliest deadline, given the clock reads `now_ms` .

Public Static Functions¶

Type	Name
bool	espos_sched_reached (uint32_t a, uint32_t b) True when `a` is at or after`b` on a modular 32-bit millisecond clock.

Macros¶

Type	Name
define	ESPOS_SCHED_HANDLE_NONE `(([espos\_sched\_handle\_t](espos__sched_8h.md#typedef-espos_sched_handle_t))0)`
define	ESPOS_SCHED_MAX_DELAY_MS `0x7FFFFFFFu`

Public Types Documentation¶

typedef espos_sched_cb_t¶

typedef void(* espos_sched_cb_t) (void *arg);

typedef espos_sched_handle_t¶

typedef uint32_t espos_sched_handle_t;

Public Functions Documentation¶

function espos_sched_add¶

Schedule cb to rundelay_ms afternow_ms , then everyperiod_ms (0 = one-shot).

esp_err_t espos_sched_add (
    espos_sched_t * s,
    uint32_t now_ms,
    uint32_t delay_ms,
    uint32_t period_ms,
    espos_sched_cb_t cb,
    void * arg,
    espos_sched_handle_t * out
)

A delay_ms of 0 is due immediately — the next espos_sched_fire() runs it.

A periodic timer's next deadline is computed from the deadline it just met, not from the moment the callback finished, so a slow callback does not make a 1000 ms timer drift into a 1050 ms one. If the loop was blocked long enough to miss whole periods, the missed ones are dropped rather than fired back to back (a catch-up burst is never what a sensor poll wants).

Parameters:

out receives the handle; may not be NULL.

Returns:

ESP_ERR_NO_MEM when every slot is in use, ESP_ERR_INVALID_ARG for a NULL callback or a delay/period beyond ESPOS_SCHED_MAX_DELAY_MS.

function espos_sched_cancel¶

Cancel a timer.

esp_err_t espos_sched_cancel (
    espos_sched_t * s,
    espos_sched_handle_t h
)

Safe from inside any callback, including the timer's own — the slot is only marked, and reaped when espos_sched_fire() unwinds, so a callback cancelling itself does not have its arguments pulled out from under the loop that is iterating the table.

Returns:

ESP_ERR_NOT_FOUND for a handle that never existed, was already cancelled, or belongs to a one-shot that has already fired. That is not an error a caller has to handle: it is the answer to "cancel this if it is still pending".

function espos_sched_count¶

Live timers (added, not yet cancelled or fired-and-done).

size_t espos_sched_count (
    const espos_sched_t * s
)

function espos_sched_fire¶

Run every timer due at now_ms and return how many fired.

size_t espos_sched_fire (
    espos_sched_t * s,
    uint32_t now_ms
)

Order among timers due at the same moment is by deadline, earliest first, and among equal deadlines by insertion — the order they were added, which is the order a wiring function created them in and therefore the only order a reader can predict.

A timer added by a callback is not fired in the same sweep even if it is already due; it goes on the next one. Otherwise a callback that re-arms itself with delay 0 would spin the loop forever inside one fire().

Re-entering fire() from a callback is refused (returns 0): the loop calls it, callbacks do not.

function espos_sched_init¶

Bind a scheduler to a caller-owned array of cap slots.

esp_err_t espos_sched_init (
    espos_sched_t * s,
    espos_sched_timer_t * slots,
    size_t cap
)

The array's contents are cleared. ESP_ERR_INVALID_ARG for a NULL argument or cap 0.

function espos_sched_next_due¶

Milliseconds until the earliest deadline, given the clock reads now_ms .

uint32_t espos_sched_next_due (
    const espos_sched_t * s,
    uint32_t now_ms
)

0 when something is already due (or overdue), UINT32_MAX when no timer is pending — which is the loop's "block until something is posted" signal.

Public Static Functions Documentation¶

function espos_sched_reached¶

True when a is at or afterb on a modular 32-bit millisecond clock.

static inline bool espos_sched_reached (
    uint32_t a,
    uint32_t b
)

Exposed because it is the whole of the wrap-safety argument and a test should be able to aim at it directly.

Macro Definition Documentation¶

define ESPOS_SCHED_HANDLE_NONE¶

#define ESPOS_SCHED_HANDLE_NONE `(( espos_sched_handle_t )0)`

define ESPOS_SCHED_MAX_DELAY_MS¶

#define ESPOS_SCHED_MAX_DELAY_MS `0x7FFFFFFFu`

The documentation for this class was generated from the following file espos_flow/include/espos_sched.h