Collaboration diagram for Event Flags:

Description

Event Flags, Event Sources and Event Listeners.

Operation mode

Each thread has a mask of pending event flags inside its Thread structure. Operations defined for event flags:

Wait, the invoking thread goes to sleep until a certain AND/OR combination of event flags becomes pending.
Clear, a mask of event flags is cleared from the pending events mask, the cleared event flags mask is returned (only the flags that were actually pending and then cleared).
Signal, an event mask is directly ORed to the mask of the signaled thread.
Broadcast, each thread registered on an Event Source is signaled with the event flags specified in its Event Listener.
Dispatch, an events mask is scanned and for each bit set to one an associated handler function is invoked. Bit masks are scanned from bit zero upward.

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 Documentation

#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.

Parameters:

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().

Parameters:

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.

Note:: Multiple Event Listeners can use the same event identifier, the listener will share the callback function.

Parameters:

`[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.

Note:: Can be used with interrupts disabled or enabled.

Parameters:

[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.

Note:: Can be called with interrupts disabled or enabled.

Parameters:

[in] esp pointer to the EventSource structure

Definition at line 118 of file chevents.h.

Typedef Documentation

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.

Function Documentation

void chEvtRegisterMask	(	EventSource *	esp,
		EventListener *	elp,
		eventmask_t	mask
	)

Registers an Event Listener on an Event Source.

Note:: Multiple Event Listeners can specify the same bits to be pended.

Parameters:

`[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, 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.

Note:: If the event listener is not registered on the specified event source then the function does nothing.; For optimal performance it is better to perform the unregister operations in inverse order of the register operations (elements are found on top of the list).

Parameters:

`[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.

Parameters:

[in] mask the events to be cleared

Returns:: The pending events that were 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().

Parameters:

[in] mask the events to be pended

Returns:: The current pending events mask.

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.

Parameters:

`[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.

Here is the call graph for this function:

void chEvtSignalI	(	Thread *	tp,
		eventmask_t	mask
	)

Pends a set of event flags on the specified Thread.

Parameters:

`[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, Thread::rdymsg, THD_STATE_WTANDEVT, and THD_STATE_WTOREVT.

Referenced by chEvtBroadcastI(), and chEvtSignal().

Here is the call graph for this function:

void chEvtBroadcast ( EventSource * esp )

Signals all the Event Listeners registered on the specified Event Source.

Parameters:

[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().

Here is the call graph for this function:

void chEvtBroadcastI ( EventSource * esp )

Signals all the Event Listeners registered on the specified Event Source.

Parameters:

[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().

Here is the call graph for this function:

void chEvtDispatch	(	const evhandler_t *	handlers,
		eventmask_t	mask
	)

Invokes the event handlers associated to an event flags mask.

Parameters:

`[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.

Note:: One and only one event is served in the function, the one with the lowest event id. The function is meant to be invoked into a loop in order to serve all the pending events.
This means that Event Listeners with a lower event identifier have an higher priority.

Parameters:

[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:

TIME_IMMEDIATE immediate timeout.
TIME_INFINITE no timeout.

Returns:: The mask of the lowest id served and cleared event.

Return values:

0

if the specified timeout expired.

Definition at line 345 of file chevents.c.

References chSchGoSleepTimeoutS(), chSysLock, chSysUnlock, Thread::ewmask, Thread::p_epending, Thread::p_u, RDY_OK, THD_STATE_WTOREVT, and TIME_IMMEDIATE.

Referenced by chibios_rt::Event::WaitOneTimeout().

Here is the call graph for this function:

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.

Parameters:

[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:

TIME_IMMEDIATE immediate timeout.
TIME_INFINITE no timeout.

Returns:: The mask of the served and cleared events.

Return values:

0

if the specified timeout expired.

Definition at line 386 of file chevents.c.

References chSchGoSleepTimeoutS(), chSysLock, chSysUnlock, Thread::ewmask, Thread::p_epending, Thread::p_u, RDY_OK, THD_STATE_WTOREVT, and TIME_IMMEDIATE.

Referenced by chibios_rt::Event::WaitAnyTimeout().

Here is the call graph for this function:

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.

Parameters:

[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:

TIME_IMMEDIATE immediate timeout.
TIME_INFINITE no timeout.

Returns:: The mask of the served and cleared events.

Return values:

0

if the specified timeout expired.

Definition at line 424 of file chevents.c.

References chSchGoSleepTimeoutS(), chSysLock, chSysUnlock, Thread::ewmask, Thread::p_epending, Thread::p_u, RDY_OK, THD_STATE_WTANDEVT, and TIME_IMMEDIATE.

Referenced by chibios_rt::Event::WaitAllTimeout().

Here is the call graph for this function:

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.

Note:: One and only one event is served in the function, the one with the lowest event id. The function is meant to be invoked into a loop in order to serve all the pending events.
This means that Event Listeners with a lower event identifier have an higher priority.

Parameters:

[in] mask mask of the events that the function should wait for, ALL_EVENTS enables all the events