source: rtems-docs/c_user/event_manager.rst @ fd6dc8c8

4.115
Last change on this file since fd6dc8c8 was fd6dc8c8, checked in by Amar Takhar <amar@…>, on 01/18/16 at 00:19:43

Split document into seperate files by section.

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