File scheduler.h

Scheduler Common interface, used by all schedulers.

In order to utilise this interface, the first member of any scheduler should be the vtable.

Every scheduler has 2 primary functions:

  1. Run each coroutine to completion (via resumes).

  2. Route coroutine signals to other coroutines.

Typedefs

typedef struct scheduler Scheduler
typedef void (*SchedulerRun)(Scheduler *scheduler)

Function prototype for running the scheduler until completion.

A scheduler will be considered complete when all its managed coroutines are run until completion.

If there are coroutines that never finish, run will also never finish.

Param scheduler:

Scheduler to run.

typedef void (*SchedulerStart)(Scheduler *scheduler)

Function prototype for preparing the scheduler for step-by-step run mode.

This should only be called once per scheduler. Preferably just before running.

Warning

This API is used in particular scenarios and is not recommended. Consider using scheduler_run instead.

Param scheduler:

Scheduler to start.

typedef bool (*SchedulerRunOnce)(Scheduler *scheduler)

Function prototype for step-by-step run mode.

Warning

This API is used in particular scenarios and is not recommended. Consider using scheduler_run instead.

Param scheduler:

Scheduler to run.

Return:

True if there is more potential work to do, else false.

typedef Result (*SchedulerNotify)(Scheduler *scheduler, CoroEventSource const *event)

Function pointer implementing the notify the scheduler of an event.

Note

This should not generally be used by the user application. The events the scheduler handles are primarily for internal use.

Param scheduler:

Scheduler to notify.

Param event:

Event to notify.

Retval RES_OK:

No error.

Retval RES_NO_MEM:

No space available in the scheduler to queue this event.

typedef Result (*SchedulerNotifyFromISR)(Scheduler *scheduler, CoroEventSource const *event)

Function pointer implementing to notify the scheduler from an ISR.

This is primarily used in ISR contexts, where communication primitives will send their event sources directly to the scheduler, instead of via the coroutine.

Param scheduler:

Scheduler to notify.

Param event:

Event to notify.

Retval RES_OK:

No error.

Retval RES_NO_MEM:

No space available in the scheduler to queue this event.

typedef Coro *(*SchedulerGetCurrentCoroutine)(Scheduler *scheduler)

Functions

void scheduler_run(Scheduler *scheduler)

Runs the scheduler until completion.

A scheduler will be considered complete when all its managed coroutines are run until completion.

If there are coroutines that never finish, run will also never finish.

Parameters:

scheduler – Scheduler to run.

void scheduler_start(Scheduler *scheduler)

Prepares the scheduler for step-by-step run mode.

This should only be called once per scheduler. Preferably just before running.

Warning

This API is used in particular scenarios and is not recommended. Consider using scheduler_run instead.

Parameters:

scheduler – Scheduler to start.

bool scheduler_run_once(Scheduler *scheduler)

Runs a single step (as part of step-by-step run mode)

Warning

This API is used in particular scenarios and is not recommended. Consider using scheduler_run instead.

Parameters:

scheduler – Scheduler to run.

Returns:

True if there is more potential work to do, else false.

static inline Result scheduler_notify(Scheduler *scheduler, CoroEventSource const *event)

Notify the scheduler of an event.

This is not typically used, as the coroutines have an internal mechanism to raise events with the scheduler.

Note

other result codes are possible, but will depend on the implementation.

Parameters:

  • scheduler – Scheduler to notify.

  • event – Event to notify.

Return values:

  • RES_OK – scheduler has been notified.

  • RES_NOTIFY_FAILED – if the scheduler has not been notified.

static inline Result scheduler_notify_from_isr(Scheduler *scheduler, CoroEventSource const *event)

Notify the scheduler of an event from an ISR.

Note

other result codes are possible, but will depend on the implementation.

Parameters:

  • scheduler – Scheduler to notify.

  • event – Event to notify.

Return values:

  • RES_OK – scheduler has been notified.

  • RES_NOTIFY_FAILED – if the scheduler has not been notified.

static inline Coro *scheduler_get_current_coroutine(Scheduler *scheduler)

Gets the current running coroutine.

Parameters:

scheduler – Scheduler to check.

Return values:

pointer – to the coroutine, or NULL if the scheduler is not running.

struct scheduler
#include <scheduler.h>

Scheduler common interface.

Public Members

SchedulerRun run
SchedulerNotify notify
SchedulerNotifyFromISR notify_from_isr
SchedulerGetCurrentCoroutine get_current_coroutine