Collaboration diagram for Event Flags:

Detailed Description

Event Flags, Event Sources and Event Listeners.

Operation mode

Each thread has a mask of pending events inside its thread_t structure. Operations defined for events:

Wait, the invoking thread goes to sleep until a certain AND/OR combination of events become pending.
Clear, a mask of events is cleared from the pending events, the cleared events mask is returned (only the events that were actually pending and then cleared).
Signal, an events mask is directly ORed to the mask of the signaled thread.
Broadcast, each thread registered on an Event Source is signaled with the events 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_CFG_USE_EVENTS option must be enabled in chconf.h.

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

Macros
#define	ALL_EVENTS ((eventmask_t)-1)
	All events allowed mask. More...

#define	EVENT_MASK(eid) ((eventmask_t)1 << (eventmask_t)(eid))
	Returns an event mask from an event identifier. More...

#define	_EVENTSOURCE_DATA(name) {(event_listener_t *)(&name)}
	Data part of a static event source initializer. More...

#define	EVENTSOURCE_DECL(name) event_source_t name = _EVENTSOURCE_DATA(name)
	Static event source initializer. More...

Typedefs
typedef struct event_source	event_source_t
	Event Source structure. More...

typedef void(*	evhandler_t) (eventid_t id)
	Event Handler callback function. More...

Data Structures
struct	event_listener
	Event Listener structure. More...

struct	event_source
	Event Source structure. More...

Functions
void	chEvtRegisterMaskWithFlags (event_source_t esp, event_listener_t elp, eventmask_t events, eventflags_t wflags)
	Registers an Event Listener on an Event Source. More...

void	chEvtUnregister (event_source_t esp, event_listener_t elp)
	Unregisters an Event Listener from its Event Source. More...

eventmask_t	chEvtGetAndClearEventsI (eventmask_t events)
	Clears the pending events specified in the events mask. More...

eventmask_t	chEvtGetAndClearEvents (eventmask_t events)
	Clears the pending events specified in the events mask. More...

eventmask_t	chEvtAddEvents (eventmask_t events)
	Adds (OR) a set of events to the current thread, this is much faster than using `chEvtBroadcast()` or `chEvtSignal()`. More...

void	chEvtBroadcastFlagsI (event_source_t *esp, eventflags_t flags)
	Signals all the Event Listeners registered on the specified Event Source. More...

eventflags_t	chEvtGetAndClearFlags (event_listener_t *elp)
	Returns the flags associated to an `event_listener_t`. More...

void	chEvtSignal (thread_t *tp, eventmask_t events)
	Adds a set of event flags directly to the specified `thread_t`. More...

void	chEvtSignalI (thread_t *tp, eventmask_t events)
	Adds a set of event flags directly to the specified `thread_t`. More...

void	chEvtBroadcastFlags (event_source_t *esp, eventflags_t flags)
	Signals all the Event Listeners registered on the specified Event Source. More...

eventflags_t	chEvtGetAndClearFlagsI (event_listener_t *elp)
	Returns the unmasked flags associated to an `event_listener_t`. More...

void	chEvtDispatch (const evhandler_t *handlers, eventmask_t events)
	Invokes the event handlers associated to an event flags mask. More...

eventmask_t	chEvtWaitOne (eventmask_t events)
	Waits for exactly one of the specified events. More...

eventmask_t	chEvtWaitAny (eventmask_t events)
	Waits for any of the specified events. More...

eventmask_t	chEvtWaitAll (eventmask_t events)
	Waits for all the specified events. More...

eventmask_t	chEvtWaitOneTimeout (eventmask_t events, sysinterval_t timeout)
	Waits for exactly one of the specified events. More...

eventmask_t	chEvtWaitAnyTimeout (eventmask_t events, sysinterval_t timeout)
	Waits for any of the specified events. More...

eventmask_t	chEvtWaitAllTimeout (eventmask_t events, sysinterval_t timeout)
	Waits for all the specified events. More...

static void	chEvtObjectInit (event_source_t *esp)
	Initializes an Event Source. More...

static void	chEvtRegisterMask (event_source_t esp, event_listener_t elp, eventmask_t events)
	Registers an Event Listener on an Event Source. More...

static void	chEvtRegister (event_source_t esp, event_listener_t elp, eventid_t event)
	Registers an Event Listener on an Event Source. More...

static bool	chEvtIsListeningI (event_source_t *esp)
	Verifies if there is at least one `event_listener_t` registered. More...

static void	chEvtBroadcast (event_source_t *esp)
	Signals all the Event Listeners registered on the specified Event Source. More...

static void	chEvtBroadcastI (event_source_t *esp)
	Signals all the Event Listeners registered on the specified Event Source. More...

static eventmask_t	chEvtAddEventsI (eventmask_t events)
	Adds (OR) a set of events to the current thread, this is much faster than using `chEvtBroadcast()` or `chEvtSignal()`. More...

static eventmask_t	chEvtGetEventsX (void)
	Returns the events mask. More...

Macro Definition Documentation

#define ALL_EVENTS ((eventmask_t)-1)

All events allowed mask.

Definition at line 92 of file chevents.h.

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

Returns an event mask from an event identifier.

Definition at line 97 of file chevents.h.

Referenced by chEvtDispatch(), and chEvtRegister().

#define _EVENTSOURCE_DATA ( name ) {(event_listener_t *)(&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 105 of file chevents.h.

#define EVENTSOURCE_DECL ( name ) event_source_t 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 114 of file chevents.h.

Typedef Documentation

typedef struct event_source event_source_t

Event Source structure.

typedef void(* evhandler_t) (eventid_t id)

Event Handler callback function.

Definition at line 83 of file chevents.h.

Function Documentation

void chEvtRegisterMaskWithFlags	(	event_source_t *	esp,
		event_listener_t *	elp,
		eventmask_t	events,
		eventflags_t	wflags
	)

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 `event_source_t` structure
[in]	elp	pointer to the `event_listener_t` structure
[in]	events	events to be ORed to the thread when the event source is broadcasted
[in]	wflags	mask of flags the listening thread is interested in

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

Definition at line 103 of file chevents.c.

References chDbgCheck, chSysLock(), chSysUnlock(), currp, event_listener::events, event_listener::flags, event_listener::listener, event_listener::next, event_source::next, and event_listener::wflags.

Referenced by chEvtRegisterMask().

Here is the call graph for this function:

void chEvtUnregister	(	event_source_t *	esp,
		event_listener_t *	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 `event_source_t` structure
[in]	elp	pointer to the `event_listener_t` structure

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

Definition at line 133 of file chevents.c.

References chDbgCheck, chSysLock(), chSysUnlock(), and event_listener::next.

Here is the call graph for this function:

eventmask_t chEvtGetAndClearEventsI ( eventmask_t events )

Clears the pending events specified in the events mask.

Parameters

[in] events the events to be cleared

Returns: The mask of pending events that were cleared.

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

References currp.

Referenced by chEvtGetAndClearEvents().

eventmask_t chEvtGetAndClearEvents ( eventmask_t events )

Clears the pending events specified in the events mask.

Parameters

[in] events the events to be cleared

Returns: The mask of 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 179 of file chevents.c.

References chEvtGetAndClearEventsI(), chSysLock(), and chSysUnlock().

Here is the call graph for this function:

eventmask_t chEvtAddEvents ( eventmask_t events )

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

Parameters

[in] events the events to be added

Returns: The mask of currently pending events.

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

Definition at line 198 of file chevents.c.

References chEvtAddEventsI(), chSysLock(), and chSysUnlock().

Here is the call graph for this function:

void chEvtBroadcastFlagsI	(	event_source_t *	esp,
		eventflags_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 event_source_t in addition to the event flags specified by the threads themselves in the event_listener_t 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 `event_source_t` 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 225 of file chevents.c.

References chDbgCheck, chDbgCheckClassI(), chEvtSignalI(), event_listener::events, event_listener::flags, event_listener::listener, event_listener::next, event_source::next, and event_listener::wflags.

Referenced by chEvtBroadcastFlags(), and chEvtBroadcastI().

Here is the call graph for this function:

eventflags_t chEvtGetAndClearFlags ( event_listener_t * elp )

Returns the flags associated to an event_listener_t.

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

Parameters

[in] elp pointer to the event_listener_t structure

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

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

Definition at line 257 of file chevents.c.

References chSysLock(), chSysUnlock(), event_listener::flags, and event_listener::wflags.

Here is the call graph for this function:

void chEvtSignal	(	thread_t *	tp,
		eventmask_t	events
	)

Adds a set of event flags directly to the specified thread_t.

Parameters

[in]	tp	the thread to be signaled
[in]	events	the events 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 276 of file chevents.c.

References chDbgCheck, chEvtSignalI(), chSchRescheduleS(), chSysLock(), and chSysUnlock().

Here is the call graph for this function:

void chEvtSignalI	(	thread_t *	tp,
		eventmask_t	events
	)

Adds a set of event flags directly to the specified thread_t.

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]	events	the events 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 298 of file chevents.c.

References CH_STATE_WTANDEVT, CH_STATE_WTOREVT, chDbgCheck, chDbgCheckClassI(), chSchReadyI(), ch_thread::epending, ch_thread::ewmask, MSG_OK, ch_thread::rdymsg, ch_thread::state, and ch_thread::u.

Referenced by chEvtBroadcastFlagsI(), and chEvtSignal().

Here is the call graph for this function:

void chEvtBroadcastFlags	(	event_source_t *	esp,
		eventflags_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 event_source_t in addition to the event flags specified by the threads themselves in the event_listener_t objects.

Parameters

[in]	esp	pointer to the `event_source_t` 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 327 of file chevents.c.

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

Referenced by chEvtBroadcast().

Here is the call graph for this function:

eventflags_t chEvtGetAndClearFlagsI ( event_listener_t * elp )

Returns the unmasked flags associated to an event_listener_t.

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

Parameters

[in] elp pointer to the event_listener_t 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 346 of file chevents.c.

References event_listener::flags, and event_listener::wflags.

void chEvtDispatch	(	const evhandler_t *	handlers,
		eventmask_t	events
	)

Invokes the event handlers associated to an event flags mask.

Parameters

[in]	events	mask of 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.

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

Definition at line 364 of file chevents.c.

References chDbgAssert, chDbgCheck, and EVENT_MASK.

eventmask_t chEvtWaitOne ( eventmask_t events )

Waits for exactly one of the specified events.

The function waits for one event among those specified in events 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] events events that the function should wait for, ALL_EVENTS enables all the events

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

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

Definition at line 399 of file chevents.c.

References CH_STATE_WTOREVT, chSchGoSleepS(), chSysLock(), chSysUnlock(), currp, ch_thread::epending, ch_thread::ewmask, and ch_thread::u.

Here is the call graph for this function:

eventmask_t chEvtWaitAny ( eventmask_t events )

Waits for any of the specified events.

The function waits for any event among those specified in events to become pending then the events are cleared and returned.

Parameters

[in] events events 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 429 of file chevents.c.

References CH_STATE_WTOREVT, chSchGoSleepS(), chSysLock(), chSysUnlock(), currp, ch_thread::epending, ch_thread::ewmask, and ch_thread::u.

Here is the call graph for this function:

eventmask_t chEvtWaitAll ( eventmask_t events )

Waits for all the specified events.

The function waits for all the events specified in events to become pending then the events are cleared and returned.

Parameters

[in] events events 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 457 of file chevents.c.

References CH_STATE_WTANDEVT, chSchGoSleepS(), chSysLock(), chSysUnlock(), currp, ch_thread::epending, ch_thread::ewmask, and ch_thread::u.

Here is the call graph for this function:

eventmask_t chEvtWaitOneTimeout	(	eventmask_t	events,
		sysinterval_t	timeout
	)

Waits for exactly one of the specified events.

The function waits for one event among those specified in events 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]	events	events that the function should wait for, `ALL_EVENTS` enables all the events
[in]	timeout	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 event id served and cleared.

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 495 of file chevents.c.

References CH_STATE_WTOREVT, chSchGoSleepTimeoutS(), chSysLock(), chSysUnlock(), currp, ch_thread::epending, ch_thread::ewmask, MSG_OK, TIME_IMMEDIATE, and ch_thread::u.

Here is the call graph for this function:

eventmask_t chEvtWaitAnyTimeout	(	eventmask_t	events,
		sysinterval_t	timeout
	)

Waits for any of the specified events.

The function waits for any event among those specified in events to become pending then the events are cleared and returned.

Parameters

[in]	events	events that the function should wait for, `ALL_EVENTS` enables all the events
[in]	timeout	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 538 of file chevents.c.

References CH_STATE_WTOREVT, chSchGoSleepTimeoutS(), chSysLock(), chSysUnlock(), currp, ch_thread::epending, ch_thread::ewmask, MSG_OK, TIME_IMMEDIATE, and ch_thread::u.

Here is the call graph for this function:

eventmask_t chEvtWaitAllTimeout	(	eventmask_t	events,
		sysinterval_t	timeout
	)

Waits for all the specified events.

The function waits for all the events specified in events to become pending then the events are cleared and returned.

Parameters

[in]	events	events that the function should wait for, `ALL_EVENTS` requires all the events
[in]	timeout	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 579 of file chevents.c.

References CH_STATE_WTANDEVT, chSchGoSleepTimeoutS(), chSysLock(), chSysUnlock(), currp, ch_thread::epending, ch_thread::ewmask, MSG_OK, TIME_IMMEDIATE, and ch_thread::u.

Here is the call graph for this function:

static void chEvtObjectInit ( event_source_t * esp )

inlinestatic

Initializes an Event Source.

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

Parameters

[in] esp pointer to the event_source_t structure

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

Definition at line 171 of file chevents.h.

References event_source::next.

static void chEvtRegisterMask	(	event_source_t *	esp,
		event_listener_t *	elp,
		eventmask_t	events
	)

inlinestatic

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 `event_source_t` structure
[out]	elp	pointer to the `event_listener_t` structure
[in]	events	the mask of events 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 190 of file chevents.h.

References chEvtRegisterMaskWithFlags().

Referenced by chEvtRegister().

Here is the call graph for this function:

static void chEvtRegister	(	event_source_t *	esp,
		event_listener_t *	elp,
		eventid_t	event
	)

inlinestatic

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 `event_source_t` structure
[out]	elp	pointer to the `event_listener_t` structure
[in]	event	numeric identifier assigned to the Event Listener. The value must range between zero and the size, in bit, of the `eventmask_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 210 of file chevents.h.

References chEvtRegisterMask(), and EVENT_MASK.

Here is the call graph for this function:

static bool chEvtIsListeningI ( event_source_t * esp )

inlinestatic

Verifies if there is at least one event_listener_t registered.

Parameters

[in] esp pointer to the event_source_t structure

Returns: The event source status.

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

References event_source::next.

static void chEvtBroadcast ( event_source_t * esp )

inlinestatic

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

Parameters

[in] esp pointer to the event_source_t structure

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

Definition at line 238 of file chevents.h.

References chEvtBroadcastFlags().

Here is the call graph for this function:

static void chEvtBroadcastI ( event_source_t * esp )

inlinestatic

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 event_source_t 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 255 of file chevents.h.

References chEvtBroadcastFlagsI().

Here is the call graph for this function:

static eventmask_t chEvtAddEventsI ( eventmask_t events )

inlinestatic

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

Parameters

[in] events the events to be added

Returns: The mask of currently pending events.

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

References currp, and event_listener::events.

Referenced by chEvtAddEvents().

static eventmask_t chEvtGetEventsX ( void )

inlinestatic

Returns the events mask.

The pending events mask is returned but not altered in any way.

Returns: The 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 282 of file chevents.h.

References currp.

Detailed Description

Operation mode

Macros

Typedefs

Data Structures

Functions

Macro Definition Documentation

Typedef Documentation

Function Documentation