Collaboration diagram for Events:

Detailed Description

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

Macro Functions
#define	chEvtObjectInit(esp)
	Initializes an Event Source. More...

#define	chEvtRegisterMask(esp, elp, events) chEvtRegisterMaskWithFlags(esp, elp, events, (eventflags_t)-1)
	Registers an Event Listener on an Event Source. More...

#define	chEvtRegister(esp, elp, event) chEvtRegisterMask(esp, elp, EVENT_MASK(event))
	Registers an Event Listener on an Event Source. More...

#define	chEvtIsListeningI(esp) (bool)((esp) != (event_source_t *)(esp)->next)
	Verifies if there is at least one `event_listener_t` registered. More...

#define	chEvtBroadcast(esp) chEvtBroadcastFlags(esp, (eventflags_t)0)
	Signals all the Event Listeners registered on the specified Event Source. More...

#define	chEvtBroadcastI(esp) chEvtBroadcastFlagsI(esp, (eventflags_t)0)
	Signals all the Event Listeners registered on the specified Event Source. More...

#define	chEvtAddEventsI(events) (nil.current->epmask \|= events)
	Adds (OR) a set of events to the current thread, this is much faster than using `chEvtBroadcast()` or `chEvtSignal()`. More...

#define	chEvtGetEventsX(void) (nil.current->epmask)
	Returns the events mask. More...

#define	chEvtWaitOne(events) chEvtWaitOneTimeout(events, TIME_INFINITE)
	Waits for exactly one of the specified events. More...

#define	chEvtWaitAny(events) chEvtWaitAnyTimeout(events, TIME_INFINITE)
	Waits for any of the specified events. More...

#define	chEvtWaitAll(events) chEvtWaitAllTimeout(events, TIME_INFINITE)
	Waits for all the specified events. 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	chEvtWaitOneTimeout (eventmask_t events, sysinterval_t timeout)
	Waits for exactly one of the specified events. More...

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

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

Macro Definition Documentation

◆ ALL_EVENTS

#define ALL_EVENTS ((eventmask_t)-1)

All events allowed mask.

Definition at line 89 of file chevt.h.

◆ EVENT_MASK

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

Returns an event mask from an event identifier.

Definition at line 94 of file chevt.h.

◆ _EVENTSOURCE_DATA

#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 102 of file chevt.h.

◆ EVENTSOURCE_DECL

#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 111 of file chevt.h.

◆ chEvtObjectInit

#define chEvtObjectInit ( esp )

Value:

  do {                                           \
  (esp)->next = (event_listener_t *)(esp);                                  \
} while (0)

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 126 of file chevt.h.

◆ chEvtRegisterMask

#define chEvtRegisterMask	(	esp,
		elp,
		events
	)	chEvtRegisterMaskWithFlags(esp, elp, events, (eventflags_t)-1)

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 144 of file chevt.h.

◆ chEvtRegister

#define chEvtRegister	(	esp,
		elp,
		event
	)	chEvtRegisterMask(esp, elp, EVENT_MASK(event))

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 160 of file chevt.h.

◆ chEvtIsListeningI

#define chEvtIsListeningI ( esp ) (bool)((esp) != (event_source_t *)(esp)->next)

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 171 of file chevt.h.

◆ chEvtBroadcast

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

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 181 of file chevt.h.

◆ chEvtBroadcastI

#define chEvtBroadcastI ( esp ) chEvtBroadcastFlagsI(esp, (eventflags_t)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 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 195 of file chevt.h.

◆ chEvtAddEventsI

#define chEvtAddEventsI ( events ) (nil.current->epmask |= 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:: 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 206 of file chevt.h.

◆ chEvtGetEventsX

#define chEvtGetEventsX ( void ) (nil.current->epmask)

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 216 of file chevt.h.

◆ chEvtWaitOne

#define chEvtWaitOne ( events ) chEvtWaitOneTimeout(events, TIME_INFINITE)

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.

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 235 of file chevt.h.

◆ chEvtWaitAny

#define chEvtWaitAny ( events ) chEvtWaitAnyTimeout(events, TIME_INFINITE)

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

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 250 of file chevt.h.

◆ chEvtWaitAll

#define chEvtWaitAll ( events ) chEvtWaitAllTimeout(events, TIME_INFINITE)

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

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 264 of file chevt.h.

Typedef Documentation

◆ event_source_t

typedef struct event_source event_source_t

Event Source structure.

◆ evhandler_t

typedef void(* evhandler_t) (eventid_t id)

Event Handler callback function.

Definition at line 80 of file chevt.h.

Function Documentation

◆ chEvtRegisterMaskWithFlags()

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 71 of file chevt.c.

References chDbgCheck, chSysLock, chSysUnlock, chThdGetSelfX, event_listener::events, event_listener::flags, event_listener::listener, event_listener::next, event_source::next, and event_listener::wflags.

◆ chEvtUnregister()

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 101 of file chevt.c.

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

◆ chEvtGetAndClearEventsI()

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 130 of file chevt.c.

References chThdGetSelfX.

Referenced by chEvtGetAndClearEvents().

◆ 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 147 of file chevt.c.

References chEvtGetAndClearEventsI(), chSysLock, and chSysUnlock.

Here is the call graph for this function:

◆ chEvtAddEvents()

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 166 of file chevt.c.

References chEvtAddEventsI, chSysLock, and chSysUnlock.

◆ chEvtBroadcastFlagsI()

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 193 of file chevt.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().

Here is the call graph for this function:

◆ chEvtGetAndClearFlags()

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 225 of file chevt.c.

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

◆ chEvtSignal()

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 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 244 of file chevt.c.

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

Here is the call graph for this function:

◆ chEvtSignalI()

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 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 264 of file chevt.c.

References chDbgCheck, chDbgCheckClassI(), and nil_thread::epmask.

Referenced by chEvtBroadcastFlagsI(), and chEvtSignal().

Here is the call graph for this function:

◆ chEvtBroadcastFlags()

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 291 of file chevt.c.

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

Here is the call graph for this function:

◆ chEvtGetAndClearFlagsI()

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 310 of file chevt.c.

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

◆ chEvtDispatch()

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 328 of file chevt.c.

References chDbgAssert, chDbgCheck, and EVENT_MASK.

◆ chEvtWaitOneTimeout()

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 366 of file chevt.c.

References chSchGoSleepTimeoutS(), chSysLock, chSysUnlock, nil_system::current, nil_thread::epmask, nil_thread::ewmask, MSG_OK, nil, NIL_STATE_WTOREVT, and TIME_IMMEDIATE.

Here is the call graph for this function:

◆ chEvtWaitAnyTimeout()

eventmask_t chEvtWaitAnyTimeout	(	eventmask_t	mask,
		sysinterval_t	timeout
	)

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]	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 411 of file chevt.c.

References chSchGoSleepTimeoutS(), chSysLock, chSysUnlock, nil_system::current, nil_thread::epmask, nil_thread::ewmask, MSG_OK, nil, NIL_STATE_WTOREVT, and TIME_IMMEDIATE.

Here is the call graph for this function:

◆ chEvtWaitAllTimeout()

eventmask_t chEvtWaitAllTimeout	(	eventmask_t	mask,
		sysinterval_t	timeout
	)

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` 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 453 of file chevt.c.

References chSchGoSleepTimeoutS(), chSysLock, chSysUnlock, nil_system::current, nil_thread::epmask, nil_thread::ewmask, MSG_OK, nil, NIL_STATE_WTANDEVT, and TIME_IMMEDIATE.

Here is the call graph for this function:

Detailed Description

Macros

Macro Functions

Typedefs

Data Structures

Functions

Macro Definition Documentation

◆ ALL_EVENTS

◆ EVENT_MASK

◆ _EVENTSOURCE_DATA

◆ EVENTSOURCE_DECL

◆ chEvtObjectInit

◆ chEvtRegisterMask

◆ chEvtRegister

◆ chEvtIsListeningI

◆ chEvtBroadcast

◆ chEvtBroadcastI

◆ chEvtAddEventsI

◆ chEvtGetEventsX

◆ chEvtWaitOne

◆ chEvtWaitAny

◆ chEvtWaitAll

Typedef Documentation

◆ event_source_t

◆ evhandler_t

Function Documentation

◆ chEvtRegisterMaskWithFlags()

◆ chEvtUnregister()

◆ chEvtGetAndClearEventsI()

◆ chEvtGetAndClearEvents()

◆ chEvtAddEvents()

◆ chEvtBroadcastFlagsI()

◆ chEvtGetAndClearFlags()

◆ chEvtSignal()

◆ chEvtSignalI()

◆ chEvtBroadcastFlags()

◆ chEvtGetAndClearFlagsI()

◆ chEvtDispatch()

◆ chEvtWaitOneTimeout()

◆ chEvtWaitAnyTimeout()

◆ chEvtWaitAllTimeout()