Events

The event manager provides a high performance method of intertask communication and synchronization. More...

Modules
	Event Set
	System Events
	Transient Event

Files
file	event.h
	Classic Event Manager API.
file	eventseize.c
	Event Manager Initialization.
file	eventsend.c
	Sends an Event Set to the Target Task.
file	eventsurrender.c
	Surrender Event.

Macros
#define	RTEMS_PENDING_EVENTS   0
	Constant used to receive the set of currently pending events in rtems_event_receive().

Functions
rtems_status_code	rtems_event_send (rtems_id id, rtems_event_set event_in)
	Sends an Event Set to the Target Task. More...
rtems_status_code	rtems_event_receive (rtems_event_set event_in, rtems_option option_set, rtems_interval ticks, rtems_event_set *event_out)
	Receives pending events. More...

Detailed Description

The event manager provides a high performance method of intertask communication and synchronization.

An event flag is used by a task (or ISR) to inform another task of the occurrence of a significant situation. Thirty-two event flags are associated with each task. A collection of one or more event flags is referred to as an event set. The data type rtems_event_set is used to manage event sets.

The application developer should remember the following key characteristics of event operations when utilizing the event manager:

• Events provide a simple synchronization facility.
• Events are aimed at tasks.
• Tasks can wait on more than one event simultaneously.
• Events are independent of one another.
• Events do not hold or transport data.
• Events are not queued. In other words, if an event is sent more than once to a task before being received, the second and subsequent send operations to that same task have no effect.

An event set is posted when it is directed (or sent) to a task. A pending event is an event that has been posted but not received. An event condition is used to specify the event set which the task desires to receive and the algorithm which will be used to determine when the request is satisfied. An event condition is satisfied based upon one of two algorithms which are selected by the user. The RTEMS_EVENT_ANY algorithm states that an event condition is satisfied when at least a single requested event is posted. The RTEMS_EVENT_ALL algorithm states that an event condition is satisfied when every requested event is posted.

An event set or condition is built by a bitwise or of the desired events. The set of valid events is RTEMS_EVENT_0 through RTEMS_EVENT_31. If an event is not explicitly specified in the set or condition, then it is not present. Events are specifically designed to be mutually exclusive, therefore bitwise or and addition operations are equivalent as long as each event appears exactly once in the event set list.

For example, when sending the event set consisting of RTEMS_EVENT_6, RTEMS_EVENT_15, and RTEMS_EVENT_31, the event parameter to the rtems_event_send() directive should be RTEMS_EVENT_6 | RTEMS_EVENT_15 | RTEMS_EVENT_31.

Function Documentation

rtems_event_receive()

rtems_status_code rtems_event_receive	(	rtems_event_set	event_in,
		rtems_option	option_set,
		rtems_interval	ticks,
		rtems_event_set *	event_out
	)

Receives pending events.

This directive attempts to receive the event condition specified in event_in. If event_in is set to RTEMS_PENDING_EVENTS, then the current pending events are returned in event_out and left pending. The RTEMS_WAIT and RTEMS_NO_WAIT options in the option_set parameter are used to specify whether or not the task is willing to wait for the event condition to be satisfied. The RTEMS_EVENT_ANY and RTEMS_EVENT_ALL are used in the option_set parameter to specify whether at least a single event or the complete event set is necessary to satisfy the event condition. The event_out parameter is returned to the calling task with the value that corresponds to the events in event_in that were satisfied.

A task can determine the pending event set by using a value of RTEMS_PENDING_EVENTS for the input event set event_in. The pending events are returned to the calling task but the event set is left unaltered.

A task can receive all of the currently pending events by using the a value of RTEMS_ALL_EVENTS for the input event set event_in and RTEMS_NO_WAIT | RTEMS_EVENT_ANY for the option set option_set. The pending events are returned to the calling task and the event set is cleared. If no events are pending then the RTEMS_UNSATISFIED status code will be returned.

If pending events satisfy the event condition, then event_out is set to the satisfied events and the pending events in the event condition are cleared. If the event condition is not satisfied and RTEMS_NO_WAIT is specified, then event_out is set to the currently satisfied events. If the calling task chooses to wait, then it will block waiting for the event condition.

If the calling task must wait for the event condition to be satisfied, then the timeout parameter is used to specify the maximum interval to wait. If it is set to RTEMS_NO_TIMEOUT, then the calling task will wait forever.

This directive only affects the events specified in event_in. Any pending events that do not correspond to any of the events specified in event_in will be left pending.

A clock tick is required to support the wait with time out functionality of this directive.

Parameters

[in]	event_in	Set of requested events (input events).
[in]	option_set	Use a bitwise or of the following options RTEMS_WAIT - task will wait for event (default), RTEMS_NO_WAIT - task should not wait, RTEMS_EVENT_ALL - return after all events (default), and RTEMS_EVENT_ANY - return after any events.
[in]	ticks	Time out in ticks. Use RTEMS_NO_TIMEOUT to wait without a time out (potentially forever).
[out]	event_out	Set of received events (output events).

Return values

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_UNSATISFIED	Input events not satisfied (only with the RTEMS_NO_WAIT option).
RTEMS_INVALID_ADDRESS	The event_out pointer is NULL.
RTEMS_TIMEOUT	Timed out waiting for events.

rtems_event_send()

rtems_status_code rtems_event_send	(	rtems_id	id,
		rtems_event_set	event_in
	)

Sends an Event Set to the Target Task.

This directive sends an event set event_in to the task specified by id.

Based upon the state of the target task, one of the following situations applies. The target task is

• blocked waiting for events. If the waiting task's input event condition is
• satisfied, then the task is made ready for execution.
• not satisfied, then the event set is posted but left pending and the task remains blocked.
• not waiting for events.
• The event set is posted and left pending.

Identical events sent to a task are not queued. In other words, the second, and subsequent, posting of an event to a task before it can perform an rtems_event_receive() has no effect.

The calling task will be preempted if it has preemption enabled and a higher priority task is unblocked as the result of this directive.

Sending an event set to a global task which does not reside on the local node will generate a request telling the remote node to send the event set to the appropriate task.

Parameters

[in]	id	Identifier of the target task. Specifying RTEMS_SELF results in the event set being sent to the calling task.
[in]	event_in	Event set sent to the target task.

Return values

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_INVALID_ID	Invalid task identifier.