ChibiOS/RT Architecture - Reference Manual - Guides |
Event Flags, Event Sources and Event Listeners.
Each thread has a mask of pending event flags inside its Thread
structure. Operations defined for event flags:
An Event Source is a special object that can be "broadcasted" by a thread or an interrupt service routine. Broadcasting an Event Source has the effect that all the threads registered on the Event Source will be signaled with an events mask.
An unlimited number of Event Sources can exists in a system and each thread can be listening on an unlimited number of them.
In order to use the Events APIs the CH_USE_EVENTS
option must be enabled in chconf.h
.
Data Structures | |
struct | EventListener |
Event Listener structure. More... | |
struct | EventSource |
Event Source structure. More... | |
Defines | |
#define | _EVENTSOURCE_DATA(name) {(void *)(&name)} |
Data part of a static event source initializer. | |
#define | EVENTSOURCE_DECL(name) EventSource name = _EVENTSOURCE_DATA(name) |
Static event source initializer. | |
#define | ALL_EVENTS ((eventmask_t)-1) |
#define | EVENT_MASK(eid) ((eventmask_t)(1 << (eid))) |
#define | chEvtRegister(esp, elp, eid) chEvtRegisterMask(esp, elp, EVENT_MASK(eid)) |
Registers an Event Listener on an Event Source. | |
#define | chEvtInit(esp) ((esp)->es_next = (EventListener *)(void *)(esp)) |
Initializes an Event Source. | |
#define | chEvtIsListening(esp) ((void *)(esp) != (void *)(esp)->es_next) |
Verifies if there is at least one EventListener registered. | |
Typedefs | |
typedef struct EventSource | EventSource |
Event Source structure. | |
typedef void(* | evhandler_t )(eventid_t) |
Event Handler callback function. | |
Functions | |
void | chEvtRegisterMask (EventSource *esp, EventListener *elp, eventmask_t mask) |
Registers an Event Listener on an Event Source. | |
void | chEvtUnregister (EventSource *esp, EventListener *elp) |
Unregisters an Event Listener from its Event Source. | |
eventmask_t | chEvtClear (eventmask_t mask) |
Clears the pending events specified in the mask. | |
eventmask_t | chEvtPend (eventmask_t mask) |
Pends a set of event flags on the current thread, this is much faster than using chEvtBroadcast() or chEvtSignal() . | |
void | chEvtSignal (Thread *tp, eventmask_t mask) |
Pends a set of event flags on the specified Thread . | |
void | chEvtSignalI (Thread *tp, eventmask_t mask) |
Pends a set of event flags on the specified Thread . | |
void | chEvtBroadcast (EventSource *esp) |
Signals all the Event Listeners registered on the specified Event Source. | |
void | chEvtBroadcastI (EventSource *esp) |
Signals all the Event Listeners registered on the specified Event Source. | |
void | chEvtDispatch (const evhandler_t *handlers, eventmask_t mask) |
Invokes the event handlers associated to an event flags mask. | |
eventmask_t | chEvtWaitOneTimeout (eventmask_t mask, systime_t time) |
Waits for exactly one of the specified events. | |
eventmask_t | chEvtWaitAnyTimeout (eventmask_t mask, systime_t time) |
Waits for any of the specified events. | |
eventmask_t | chEvtWaitAllTimeout (eventmask_t mask, systime_t time) |
Waits for all the specified events. | |
eventmask_t | chEvtWaitOne (eventmask_t mask) |
Waits for exactly one of the specified events. | |
eventmask_t | chEvtWaitAny (eventmask_t mask) |
Waits for any of the specified events. | |
eventmask_t | chEvtWaitAll (eventmask_t mask) |
Waits for all the specified events. |
#define _EVENTSOURCE_DATA | ( | name | ) | {(void *)(&name)} |
Data part of a static event source initializer.
This macro should be used when statically initializing an event source that is part of a bigger structure.
name | the name of the event source variable |
Definition at line 71 of file chevents.h.
#define EVENTSOURCE_DECL | ( | name | ) | EventSource name = _EVENTSOURCE_DATA(name) |
Static event source initializer.
Statically initialized event sources require no explicit initialization using chEvtInit()
.
name | the name of the event source variable |
Definition at line 80 of file chevents.h.
#define ALL_EVENTS ((eventmask_t)-1) |
All events allowed mask.
Definition at line 83 of file chevents.h.
#define EVENT_MASK | ( | eid | ) | ((eventmask_t)(1 << (eid))) |
Returns the event mask from the event identifier.
Definition at line 86 of file chevents.h.
Referenced by chEvtDispatch().
#define chEvtRegister | ( | esp, | |||
elp, | |||||
eid | ) | chEvtRegisterMask(esp, elp, EVENT_MASK(eid)) |
Registers an Event Listener on an Event Source.
[in] | esp | pointer to the EventSource structure |
[out] | elp | pointer to the EventListener structure |
[in] | eid | numeric identifier assigned to the Event Listener. The identifier is used as index for the event callback function. The value must range between zero and the size, in bit, of the eventid_t type minus one. |
Definition at line 101 of file chevents.h.
Referenced by chibios_rt::Event::Register().
#define chEvtInit | ( | esp | ) | ((esp)->es_next = (EventListener *)(void *)(esp)) |
Initializes an Event Source.
[in] | esp | pointer to the EventSource structure |
Definition at line 109 of file chevents.h.
Referenced by canObjectInit(), chibios_rt::Event::Event(), macObjectInit(), mmcObjectInit(), and sdObjectInit().
#define chEvtIsListening | ( | esp | ) | ((void *)(esp) != (void *)(esp)->es_next) |
Verifies if there is at least one EventListener
registered.
[in] | esp | pointer to the EventSource structure |
Definition at line 118 of file chevents.h.
typedef struct EventSource EventSource |
Event Source structure.
typedef void(* evhandler_t)(eventid_t) |
Event Handler callback function.
Definition at line 124 of file chevents.h.
void chEvtRegisterMask | ( | EventSource * | esp, | |
EventListener * | elp, | |||
eventmask_t | mask | |||
) |
Registers an Event Listener on an Event Source.
[in] | esp | pointer to the EventSource structure |
[in] | elp | pointer to the EventListener structure |
[in] | mask | the mask of event flags to be pended to the thread when the event source is broadcasted |
Definition at line 74 of file chevents.c.
References chDbgCheck, chSysLock, chSysUnlock, currp, EventListener::el_listener, EventListener::el_mask, EventListener::el_next, and EventSource::es_next.
Referenced by chibios_rt::Event::RegisterMask().
void chEvtUnregister | ( | EventSource * | esp, | |
EventListener * | elp | |||
) |
Unregisters an Event Listener from its Event Source.
[in] | esp | pointer to the EventSource structure |
[in] | elp | pointer to the EventListener structure |
Definition at line 97 of file chevents.c.
References chDbgCheck, chSysLock, chSysUnlock, and EventListener::el_next.
Referenced by chibios_rt::Event::Unregister().
eventmask_t chEvtClear | ( | eventmask_t | mask | ) |
Clears the pending events specified in the mask.
[in] | mask | the events to be cleared |
Definition at line 120 of file chevents.c.
References chSysLock, chSysUnlock, and currp.
Referenced by chibios_rt::Event::Clear().
eventmask_t chEvtPend | ( | eventmask_t | mask | ) |
Pends a set of event flags on the current thread, this is much faster than using chEvtBroadcast()
or chEvtSignal()
.
[in] | mask | the events to be pended |
Definition at line 139 of file chevents.c.
References chSysLock, chSysUnlock, and currp.
Referenced by chibios_rt::Event::Pend().
void chEvtSignal | ( | Thread * | tp, | |
eventmask_t | mask | |||
) |
Pends a set of event flags on the specified Thread
.
[in] | tp | the thread to be signaled |
[in] | mask | the event flags set to be pended |
Definition at line 155 of file chevents.c.
References chDbgCheck, chEvtSignalI(), chSchRescheduleS(), chSysLock, and chSysUnlock.
void chEvtSignalI | ( | Thread * | tp, | |
eventmask_t | mask | |||
) |
Pends a set of event flags on the specified Thread
.
[in] | tp | the thread to be signaled |
[in] | mask | the event flags set to be pended |
Definition at line 171 of file chevents.c.
References chDbgCheck, chSchReadyI(), Thread::ewmask, Thread::p_epending, Thread::p_state, Thread::p_u, RDY_OK, Thread::rdymsg, THD_STATE_WTANDEVT, and THD_STATE_WTOREVT.
Referenced by chEvtBroadcastI(), and chEvtSignal().
void chEvtBroadcast | ( | EventSource * | esp | ) |
Signals all the Event Listeners registered on the specified Event Source.
[in] | esp | pointer to the EventSource structure |
Definition at line 190 of file chevents.c.
References chEvtBroadcastI(), chSchRescheduleS(), chSysLock, and chSysUnlock.
Referenced by chibios_rt::Event::Broadcast().
void chEvtBroadcastI | ( | EventSource * | esp | ) |
Signals all the Event Listeners registered on the specified Event Source.
[in] | esp | pointer to the EventSource structure |
Definition at line 204 of file chevents.c.
References chDbgCheck, chEvtSignalI(), EventListener::el_listener, EventListener::el_mask, EventListener::el_next, and EventSource::es_next.
Referenced by canSleep(), canWakeup(), chEvtBroadcast(), sdAddFlagsI(), sdIncomingDataI(), sdRequestDataI(), and tmrfunc().
void chEvtDispatch | ( | const evhandler_t * | handlers, | |
eventmask_t | mask | |||
) |
Invokes the event handlers associated to an event flags mask.
[in] | mask | mask of the events to be dispatched |
[in] | handlers | an array of evhandler_t . The array must have size equal to the number of bits in eventmask_t. |
Definition at line 223 of file chevents.c.
References chDbgAssert, chDbgCheck, and EVENT_MASK.
Referenced by chibios_rt::Event::Dispatch().
eventmask_t chEvtWaitOneTimeout | ( | eventmask_t | mask, | |
systime_t | time | |||
) |
Waits for exactly one of the specified events.
The function waits for one event among those specified in mask
to become pending then the event is cleared and returned.
[in] | mask | mask of the events that the function should wait for, ALL_EVENTS enables all the events |
[in] | time | the number of ticks before the operation timeouts, the following special values are allowed:
|
0 | if the specified timeout expired. |
Definition at line 345 of file chevents.c.
References chSchGoSleepTimeoutS(), chSysLock, chSysUnlock, currp, Thread::ewmask, Thread::p_epending, Thread::p_u, RDY_OK, THD_STATE_WTOREVT, and TIME_IMMEDIATE.
Referenced by chibios_rt::Event::WaitOneTimeout().
eventmask_t chEvtWaitAnyTimeout | ( | eventmask_t | mask, | |
systime_t | time | |||
) |
Waits for any of the specified events.
The function waits for any event among those specified in mask
to become pending then the events are cleared and returned.
[in] | mask | mask of the events that the function should wait for, ALL_EVENTS enables all the events |
[in] | time | the number of ticks before the operation timeouts, the following special values are allowed:
|
0 | if the specified timeout expired. |
Definition at line 382 of file chevents.c.
References chSchGoSleepTimeoutS(), chSysLock, chSysUnlock, currp, Thread::ewmask, Thread::p_epending, Thread::p_u, RDY_OK, THD_STATE_WTOREVT, and TIME_IMMEDIATE.
Referenced by chibios_rt::Event::WaitAnyTimeout().
eventmask_t chEvtWaitAllTimeout | ( | eventmask_t | mask, | |
systime_t | time | |||
) |
Waits for all the specified events.
The function waits for all the events specified in mask
to become pending then the events are cleared and returned.
[in] | mask | mask of the event ids that the function should wait for |
[in] | time | the number of ticks before the operation timeouts, the following special values are allowed:
|
0 | if the specified timeout expired. |
Definition at line 416 of file chevents.c.
References chSchGoSleepTimeoutS(), chSysLock, chSysUnlock, currp, Thread::ewmask, Thread::p_epending, Thread::p_u, RDY_OK, THD_STATE_WTANDEVT, and TIME_IMMEDIATE.
Referenced by chibios_rt::Event::WaitAllTimeout().
eventmask_t chEvtWaitOne | ( | eventmask_t | mask | ) |
Waits for exactly one of the specified events.
The function waits for one event among those specified in mask
to become pending then the event is cleared and returned.
[in] | mask | mask of the events that the function should wait for, ALL_EVENTS enables all the events |
Definition at line 256 of file chevents.c.
References chSchGoSleepS(), chSysLock, chSysUnlock, currp, Thread::ewmask, Thread::p_epending, Thread::p_u, and THD_STATE_WTOREVT.
Referenced by chibios_rt::Event::WaitOne().
eventmask_t chEvtWaitAny | ( | eventmask_t | mask | ) |
Waits for any of the specified events.
The function waits for any event among those specified in mask
to become pending then the events are cleared and returned.
[in] | mask | mask of the events that the function should wait for, ALL_EVENTS enables all the events |
Definition at line 283 of file chevents.c.
References chSchGoSleepS(), chSysLock, chSysUnlock, currp, Thread::ewmask, Thread::p_epending, Thread::p_u, and THD_STATE_WTOREVT.
Referenced by chibios_rt::Event::WaitAny().
eventmask_t chEvtWaitAll | ( | eventmask_t | mask | ) |
Waits for all the specified events.
The function waits for all the events specified in mask
to become pending then the events are cleared and returned.
[in] | mask | mask of the event ids that the function should wait for |
Definition at line 308 of file chevents.c.
References chSchGoSleepS(), chSysLock, chSysUnlock, currp, Thread::ewmask, Thread::p_epending, Thread::p_u, and THD_STATE_WTANDEVT.
Referenced by chibios_rt::Event::WaitAll().