File event.h
Event communication primitive.
Enables coroutines to signal each other in a lightweight manner, as compared to the queue API.
These are designed to be a multi producer and single consumer, where the consumer is a coroutine.
An event consists of 32 bit flags. Each can be set. It is expected the consumer is responsible for clearing the bits, while the producer is responsible for setting them.
A producer can only set bits, it cannot clear them.
Functions
-
Event *event_create_static(Event *event, Flags initial)
Initialise an event structure with the initial set of flags.
- Parameters:
event – Event to initialise.
initial – Initial flags to use.
- Returns:
Pointer to the same event passed in, or NULL if initialisation failed.
-
Event *event_create(Flags initial)
Dynamically create an event.
- Parameters:
initial – Initial flags to assign.
- Returns:
Pointer to the created event, or NULL if it failed to create.
-
void event_free(Event *event)
Frees an event dynamically allocated with event_create.
- Parameters:
event – Event previously created with event_create.
-
void event_set(Event *event, Flags mask)
Sets the event flags.
- Parameters:
event – Event to set.
mask – Mask to set.
-
Result event_set_no_wait(Event *event, Flags mask)
Sets the event flags without yielding.
- Parameters:
event – Event to set.
mask – Mask to set.
- Return values:
RES_OK – if the event was set.
RES_NOTIFY_FAILED – if the scheduler could not be notified. This is a critical error.
-
Result event_set_from_isr(Event *event, Flags mask)
Sets the event flags from an ISR.
- Parameters:
event – Event to set.
mask – Mask to set.
- Return values:
RES_OK – if the event was set.
RES_NOTIFY_FAILED – if the scheduler could not be notified. This is a critical error.
-
Flags event_get(Event *event, Flags mask, Flags clear_mask, bool wait_for_all, PlatformTick timeout)
Waits on the specific event flags.
- Parameters:
event – Event to wait on.
mask – Mask to wait on, can be used to ignore flags.
clear_mask – Flags to clear after the wait has finished.
wait_for_all – If true, all flags must be set before the coroutine will yield. This effective sets if the mask uses “OR” or “AND” for its wait logic.
timeout – Number of ticks to wait before timing out.
- Returns:
Triggered flags. When a timeout is provided, flags may return zero if the finite timeout has elapsed. Otherwise, this function will always return a non-zero flag value.
-
Flags event_get_no_wait(Event *event, Flags mask, Flags clear_mask)
Inspects the event flags without waiting.
Unlike the yielding version, we cannot specify the “OR” or “AND” behaviour, as we do not block either way.
- Parameters:
event – Event to inspect.
mask – Mask to look for any flag bits that are set.
clear_mask – Mask to apply to clear any bits after inspection. Clear mask is only applied if the return value is non-zero.
- Returns:
The bits extracted from the mask. If this is 0, it means no flags were set.
-
Flags event_get_from_isr(Event *event, Flags mask, Flags clear_mask)
Inspects the event flags from an ISR.
- Parameters:
event – Event to inspect.
mask – Mask to look for any flag bits that are set.
clear_mask – Mask to apply to clear any bits after inspection. Clear mask is only applied if the return value is non-zero.
- Returns:
The bits extracted from the mask. If this is 0, it means no flags were set.
-
struct event