source: rtems-docs/c_user/event_manager.rst @ 489740f

4.115
Last change on this file since 489740f was 489740f, checked in by Chris Johns <chrisj@…>, on 05/20/16 at 02:47:09

Set SPDX License Identifier in each source file.

  • Property mode set to 100644
File size: 10.7 KB
Line 
1.. comment SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. COMMENT: COPYRIGHT (c) 1988-2008.
4.. COMMENT: On-Line Applications Research Corporation (OAR).
5.. COMMENT: All rights reserved.
6
7Event Manager
8#############
9
10.. index:: events
11
12Introduction
13============
14
15The event manager provides a high performance method of intertask communication
16and synchronization.  The directives provided by the event manager are:
17
18- rtems_event_send_ - Send event set to a task
19- rtems_event_receive_ - Receive event condition
20
21Background
22==========
23
24Event Sets
25----------
26.. index:: event flag, definition
27.. index:: event set, definition
28.. index:: rtems_event_set
29
30An event flag is used by a task (or ISR) to inform another task of the
31occurrence of a significant situation.  Thirty-two event flags are associated
32with each task.  A collection of one or more event flags is referred to as an
33event set.  The data type ``rtems_event_set`` is used to manage event sets.
34
35The application developer should remember the following key characteristics of
36event operations when utilizing the event manager:
37
38- Events provide a simple synchronization facility.
39
40- Events are aimed at tasks.
41
42- Tasks can wait on more than one event simultaneously.
43
44- Events are independent of one another.
45
46- Events do not hold or transport data.
47
48- Events are not queued.  In other words, if an event is sent more than once to
49  a task before being received, the second and subsequent send operations to
50  that same task have no effect.
51
52An event set is posted when it is directed (or sent) to a task.  A pending
53event is an event that has been posted but not received.  An event condition is
54used to specify the event set which the task desires to receive and the
55algorithm which will be used to determine when the request is satisfied. An
56event condition is satisfied based upon one of two algorithms which are
57selected by the user.  The ``RTEMS_EVENT_ANY`` algorithm states that an event
58condition is satisfied when at least a single requested event is posted.  The
59``RTEMS_EVENT_ALL`` algorithm states that an event condition is satisfied when
60every requested event is posted.
61
62Building an Event Set or Condition
63----------------------------------
64.. index:: event condition, building
65.. index:: event set, building
66
67An event set or condition is built by a bitwise OR of the desired events.  The
68set of valid events is ``RTEMS_EVENT_0`` through ``RTEMS_EVENT_31``.  If an
69event is not explicitly specified in the set or condition, then it is not
70present.  Events are specifically designed to be mutually exclusive, therefore
71bitwise OR and addition operations are equivalent as long as each event appears
72exactly once in the event set list.
73
74For example, when sending the event set consisting of ``RTEMS_EVENT_6``,
75``RTEMS_EVENT_15``, and ``RTEMS_EVENT_31``, the event parameter to the
76``rtems_event_send`` directive should be ``RTEMS_EVENT_6 | RTEMS_EVENT_15 |
77RTEMS_EVENT_31``.
78
79Building an EVENT_RECEIVE Option Set
80------------------------------------
81
82In general, an option is built by a bitwise OR of the desired option
83components.  The set of valid options for the ``rtems_event_receive`` directive
84are listed in the following table:
85
86.. list-table::
87 :class: rtems-table
88
89 * - ``RTEMS_WAIT``
90   - task will wait for event (default)
91 * - ``RTEMS_NO_WAIT``
92   - task should not wait
93 * - ``RTEMS_EVENT_ALL``
94   - return after all events (default)
95 * - ``RTEMS_EVENT_ANY``
96   - return after any events
97
98Option values are specifically designed to be mutually exclusive, therefore
99bitwise OR and addition operations are equivalent as long as each option
100appears exactly once in the component list.  An option listed as a default is
101not required to appear in the option list, although it is a good programming
102practice to specify default options.  If all defaults are desired, the option
103``RTEMS_DEFAULT_OPTIONS`` should be specified on this call.
104
105This example demonstrates the option parameter needed to poll for all events in
106a particular event condition to arrive.  The option parameter passed to the
107``rtems_event_receive`` directive should be either ``RTEMS_EVENT_ALL |
108RTEMS_NO_WAIT`` or ``RTEMS_NO_WAIT``.  The option parameter can be set to
109``RTEMS_NO_WAIT`` because ``RTEMS_EVENT_ALL`` is the default condition for
110``rtems_event_receive``.
111
112Operations
113==========
114
115Sending an Event Set
116--------------------
117
118The ``rtems_event_send`` directive allows a task (or an ISR) to direct an event
119set to a target task.  Based upon the state of the target task, one of the
120following situations applies:
121
122- Target Task is Blocked Waiting for Events
123
124  - If the waiting task's input event condition is satisfied, then the task is
125    made ready for execution.
126
127  - If the waiting task's input event condition is not satisfied, then the
128    event set is posted but left pending and the task remains blocked.
129
130- Target Task is Not Waiting for Events
131
132  - The event set is posted and left pending.
133
134Receiving an Event Set
135----------------------
136
137The ``rtems_event_receive`` directive is used by tasks to accept a specific
138input event condition.  The task also specifies whether the request is
139satisfied when all requested events are available or any single requested event
140is available.  If the requested event condition is satisfied by pending events,
141then a successful return code and the satisfying event set are returned
142immediately.  If the condition is not satisfied, then one of the following
143situations applies:
144
145- By default, the calling task will wait forever for the event condition to be
146  satisfied.
147
148- Specifying the ``RTEMS_NO_WAIT`` option forces an immediate return with an
149  error status code.
150
151- Specifying a timeout limits the period the task will wait before returning
152  with an error status code.
153
154Determining the Pending Event Set
155---------------------------------
156
157A task can determine the pending event set by calling the
158``rtems_event_receive`` directive with a value of ``RTEMS_PENDING_EVENTS`` for
159the input event condition.  The pending events are returned to the calling task
160but the event set is left unaltered.
161
162Receiving all Pending Events
163----------------------------
164
165A task can receive all of the currently pending events by calling the
166``rtems_event_receive`` directive with a value of ``RTEMS_ALL_EVENTS`` for the
167input event condition and ``RTEMS_NO_WAIT | RTEMS_EVENT_ANY`` for the option
168set.  The pending events are returned to the calling task and the event set is
169cleared.  If no events are pending then the ``RTEMS_UNSATISFIED`` status code
170will be returned.
171
172Directives
173==========
174
175This section details the event manager's directives.  A subsection is dedicated
176to each of this manager's directives and describes the calling sequence,
177related constants, usage, and status codes.
178
179.. _rtems_event_send:
180
181EVENT_SEND - Send event set to a task
182-------------------------------------
183.. index:: send event set to a task
184
185**CALLING SEQUENCE:**
186
187.. index:: rtems_event_send
188
189.. code-block:: c
190
191    rtems_status_code rtems_event_send (
192        rtems_id         id,
193        rtems_event_set  event_in
194    );
195
196**DIRECTIVE STATUS CODES:**
197
198.. list-table::
199 :class: rtems-table
200
201 * - ``RTEMS_SUCCESSFUL``
202   - event set sent successfully
203 * - ``RTEMS_INVALID_ID``
204   - invalid task id
205
206**DESCRIPTION:**
207
208This directive sends an event set, event_in, to the task specified by id.  If a
209blocked task's input event condition is satisfied by this directive, then it
210will be made ready.  If its input event condition is not satisfied, then the
211events satisfied are updated and the events not satisfied are left pending.  If
212the task specified by id is not blocked waiting for events, then the events
213sent are left pending.
214
215**NOTES:**
216
217Specifying ``RTEMS_SELF`` for id results in the event set being sent to the
218calling task.
219
220Identical events sent to a task are not queued.  In other words, the second,
221and subsequent, posting of an event to a task before it can perform an
222``rtems_event_receive`` has no effect.
223
224The calling task will be preempted if it has preemption enabled and a higher
225priority task is unblocked as the result of this directive.
226
227Sending an event set to a global task which does not reside on the local node
228will generate a request telling the remote node to send the event set to the
229appropriate task.
230
231.. _rtems_event_receive:
232
233EVENT_RECEIVE - Receive event condition
234---------------------------------------
235.. index:: receive event condition
236
237**CALLING SEQUENCE:**
238
239.. index:: rtems_event_receive
240
241.. code-block:: c
242
243    rtems_status_code rtems_event_receive (
244        rtems_event_set  event_in,
245        rtems_option     option_set,
246        rtems_interval   ticks,
247        rtems_event_set *event_out
248    );
249
250**DIRECTIVE STATUS CODES:**
251
252.. list-table::
253 :class: rtems-table
254
255 * - ``RTEMS_SUCCESSFUL``
256   - event received successfully
257 * - ``RTEMS_UNSATISFIED``
258   - input event not satisfied (``RTEMS_NO_WAIT``)
259 * - ``RTEMS_INVALID_ADDRESS``
260   - ``event_out`` is NULL
261 * - ``RTEMS_TIMEOUT``
262   - timed out waiting for event
263
264**DESCRIPTION:**
265
266This directive attempts to receive the event condition specified in event_in.
267If event_in is set to ``RTEMS_PENDING_EVENTS``, then the current pending events
268are returned in event_out and left pending.  The ``RTEMS_WAIT`` and
269``RTEMS_NO_WAIT`` options in the option_set parameter are used to specify
270whether or not the task is willing to wait for the event condition to be
271satisfied. ``RTEMS_EVENT_ANY`` and ``RTEMS_EVENT_ALL`` are used in the
272option_set parameter are used to specify whether a single event or the complete
273event set is necessary to satisfy the event condition.  The event_out parameter
274is returned to the calling task with the value that corresponds to the events
275in event_in that were satisfied.
276
277If pending events satisfy the event condition, then event_out is set to the
278satisfied events and the pending events in the event condition are cleared.  If
279the event condition is not satisfied and ``RTEMS_NO_WAIT`` is specified, then
280event_out is set to the currently satisfied events.  If the calling task
281chooses to wait, then it will block waiting for the event condition.
282
283If the calling task must wait for the event condition to be satisfied, then the
284timeout parameter is used to specify the maximum interval to wait.  If it is
285set to ``RTEMS_NO_TIMEOUT``, then the calling task will wait forever.
286
287**NOTES:**
288
289This directive only affects the events specified in event_in.  Any pending
290events that do not correspond to any of the events specified in event_in will
291be left pending.
292
293The following event receive option constants are defined by RTEMS:
294
295.. list-table::
296 :class: rtems-table
297
298 * - ``RTEMS_WAIT``
299   - task will wait for event (default)
300 * - ``RTEMS_NO_WAIT``
301   - task should not wait
302 * - ``RTEMS_EVENT_ALL``
303   - return after all events (default)
304 * - ``RTEMS_EVENT_ANY``
305   - return after any events
306
307A clock tick is required to support the functionality of this directive.
Note: See TracBrowser for help on using the repository browser.