Collaboration diagram for Event Flags:

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

Precondition:: In order to use the Events APIs the CH_USE_EVENTS option must be enabled in chconf.h.

Postcondition:: Enabling events requires 1-4 (depending on the architecture) extra bytes in the Thread structure.

Data Structures
struct	EventListener
	Event Listener structure. More...
struct	EventSource
	Event Source structure. More...
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	chEvtGetAndClearEvents (eventmask_t mask)
	Clears the pending events specified in the mask.
eventmask_t	chEvtAddEvents (eventmask_t mask)
	Adds (OR) a set of event flags on the current thread, this is much faster than using `chEvtBroadcast()` or `chEvtSignal()`.
flagsmask_t	chEvtGetAndClearFlags (EventListener *elp)
	Returns the flags associated to an `EventListener`.
flagsmask_t	chEvtGetAndClearFlagsI (EventListener *elp)
	Returns the flags associated to an `EventListener`.
void	chEvtSignal (Thread *tp, eventmask_t mask)
	Adds a set of event flags directly to specified `Thread`.
void	chEvtSignalI (Thread *tp, eventmask_t mask)
	Adds a set of event flags directly to specified `Thread`.
void	chEvtBroadcastFlags (EventSource *esp, flagsmask_t flags)
	Signals all the Event Listeners registered on the specified Event Source.
void	chEvtBroadcastFlagsI (EventSource *esp, flagsmask_t flags)
	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.
Macro Functions
#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	chEvtIsListeningI(esp) ((void )(esp) != (void )(esp)->es_next)
	Verifies if there is at least one `EventListener` registered.
#define	chEvtBroadcast(esp) chEvtBroadcastFlags(esp, 0)
	Signals all the Event Listeners registered on the specified Event Source.
#define	chEvtBroadcastI(esp) chEvtBroadcastFlagsI(esp, 0)
	Signals all the Event Listeners registered on the specified Event Source.
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)
	All events allowed mask.
#define	EVENT_MASK(eid) ((eventmask_t)(1 << (eid)))
	Returns an event mask from an event identifier.
Typedefs
typedef struct EventSource	EventSource
	Event Source structure.
typedef void(*	evhandler_t )(eventid_t)
	Event Handler callback function.

Function Documentation

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

Registers an Event Listener on an Event Source.

Once a thread has registered as listener on an event source it will be notified of all events broadcasted there.

Note:: Multiple Event Listeners can specify the same bits to be ORed to different threads.

Parameters:

[in]	esp	pointer to the `EventSource` structure
[in]	elp	pointer to the `EventListener` structure
[in]	mask	the mask of event flags to be ORed to the thread when the event source is broadcasted

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 78 of file chevents.c.

References chDbgCheck, chSysLock, chSysUnlock, currp, EventListener::el_flags, EventListener::el_listener, EventListener::el_mask, EventListener::el_next, and EventSource::es_next.

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

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 104 of file chevents.c.

References chDbgCheck, chSysLock, chSysUnlock, and EventListener::el_next.

eventmask_t chEvtGetAndClearEvents ( 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.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 129 of file chevents.c.

References chSysLock, chSysUnlock, and currp.

eventmask_t chEvtAddEvents ( eventmask_t mask )

Adds (OR) a set of event flags on the current thread, this is much faster than using chEvtBroadcast() or chEvtSignal().

Parameters:

[in] mask the event flags to be ORed

Returns:: The current pending events mask.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 150 of file chevents.c.

References chSysLock, chSysUnlock, and currp.

flagsmask_t chEvtGetAndClearFlags ( EventListener * elp )

Returns the flags associated to an EventListener.

The flags are returned and the EventListener flags mask is cleared.

Parameters:

[in] elp pointer to the EventListener structure

Returns:: The flags added to the listener by the associated event source.

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 202 of file chevents.c.

References chSysLock, chSysUnlock, and EventListener::el_flags.

flagsmask_t chEvtGetAndClearFlagsI ( EventListener * elp )

Returns the flags associated to an EventListener.

The flags are returned and the EventListener flags mask is cleared.

Parameters:

[in] elp pointer to the EventListener structure

Returns:: The flags added to the listener by the associated event source.

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 290 of file chevents.c.

References EventListener::el_flags.

void chEvtSignal	(	Thread *	tp,
		eventmask_t	mask
	)

Adds a set of event flags directly to specified Thread.

Parameters:

[in]	tp	the thread to be signaled
[in]	mask	the event flags set to be ORed

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 222 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
	)

Adds a set of event flags directly to specified Thread.

Postcondition:: This function does not reschedule so a call to a rescheduling function must be performed before unlocking the kernel. Note that interrupt handlers always reschedule on exit so an explicit reschedule must not be performed in ISRs.

Parameters:

[in]	tp	the thread to be signaled
[in]	mask	the event flags set to be ORed

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 244 of file chevents.c.

References chDbgCheck, chDbgCheckClassI(), chSchReadyI(), Thread::ewmask, Thread::p_epending, Thread::p_state, RDY_OK, Thread::rdymsg, THD_STATE_WTANDEVT, and THD_STATE_WTOREVT.

Referenced by chEvtBroadcastFlagsI(), and chEvtSignal().

Here is the call graph for this function:

void chEvtBroadcastFlags	(	EventSource *	esp,
		flagsmask_t	flags
	)

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

This function variants ORs the specified event flags to all the threads registered on the EventSource in addition to the event flags specified by the threads themselves in the EventListener objects.

Parameters:

[in]	esp	pointer to the `EventSource` structure
[in]	flags	the flags set to be added to the listener flags mask

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 271 of file chevents.c.

References chEvtBroadcastFlagsI(), chSchRescheduleS(), chSysLock, and chSysUnlock.

Here is the call graph for this function:

void chEvtBroadcastFlagsI	(	EventSource *	esp,
		flagsmask_t	flags
	)

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

This function variants ORs the specified event flags to all the threads registered on the EventSource in addition to the event flags specified by the threads themselves in the EventListener objects.

Postcondition:: This function does not reschedule so a call to a rescheduling function must be performed before unlocking the kernel. Note that interrupt handlers always reschedule on exit so an explicit reschedule must not be performed in ISRs.

Parameters:

[in]	esp	pointer to the `EventSource` structure
[in]	flags	the flags set to be added to the listener flags mask

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 177 of file chevents.c.

References chDbgCheck, chDbgCheckClassI(), chEvtSignalI(), EventListener::el_flags, EventListener::el_listener, EventListener::el_mask, EventListener::el_next, and EventSource::es_next.

Referenced by chEvtBroadcastFlags().

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 event flags to be dispatched
[in]	handlers	an array of `evhandler_t`. The array must have size equal to the number of bits in eventmask_t.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 308 of file chevents.c.

References chDbgAssert, chDbgCheck, and EVENT_MASK.

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 event flags 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 operation has timed out.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 439 of file chevents.c.

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

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 event flags 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 operation has timed out.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 482 of file chevents.c.

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

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 flags that the function should wait for, `ALL_EVENTS` requires 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 operation has timed out.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 523 of file chevents.c.

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

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 event flags that the function should wait for, ALL_EVENTS enables all the events

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

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 343 of file chevents.c.

References chSchGoSleepS(), chSysLock, chSysUnlock, currp, Thread::ewmask, Thread::p_epending, and THD_STATE_WTOREVT.

Here is the call graph for this function:

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.

Parameters:

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

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

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 372 of file chevents.c.

References chSchGoSleepS(), chSysLock, chSysUnlock, currp, Thread::ewmask, Thread::p_epending, and THD_STATE_WTOREVT.

Here is the call graph for this function:

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.

Parameters:

[in] mask mask of the event flags that the function should wait for, ALL_EVENTS requires all the events

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

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 400 of file chevents.c.

References chSchGoSleepS(), chSysLock, chSysUnlock, currp, Thread::ewmask, Thread::p_epending, and THD_STATE_WTANDEVT.

Here is the call graph for this function:

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 75 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 84 of file chevents.h.

#define ALL_EVENTS ((eventmask_t)-1)

All events allowed mask.

Definition at line 89 of file chevents.h.

#define EVENT_MASK ( eid ) ((eventmask_t)(1 << (eid)))

Returns an event mask from an event identifier.

Definition at line 94 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.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 115 of file chevents.h.

#define chEvtInit ( esp ) ((esp)->es_next = (EventListener *)(void *)(esp))

Initializes an Event Source.

Note:: This function can be invoked before the kernel is initialized because it just prepares a EventSource structure.

Parameters:

[in] esp pointer to the EventSource structure

Function Class:: Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 127 of file chevents.h.

#define chEvtIsListeningI ( esp ) ((void *)(esp) != (void *)(esp)->es_next)

Verifies if there is at least one EventListener registered.

Parameters:

[in] esp pointer to the EventSource structure

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 137 of file chevents.h.

#define chEvtBroadcast ( esp ) chEvtBroadcastFlags(esp, 0)

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

Parameters:

[in] esp pointer to the EventSource structure

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 148 of file chevents.h.

#define chEvtBroadcastI ( esp ) chEvtBroadcastFlagsI(esp, 0)

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

Postcondition:: This function does not reschedule so a call to a rescheduling function must be performed before unlocking the kernel. Note that interrupt handlers always reschedule on exit so an explicit reschedule must not be performed in ISRs.

Parameters:

[in] esp pointer to the EventSource structure

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 162 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 67 of file chevents.h.

Detailed Description

Operation mode

Data Structures

Functions

Macro Functions

Defines

Typedefs

Function Documentation

Define Documentation

Typedef Documentation