source: rtems/doc/user/event.t @ 106942b

Last change on this file since 106942b was 6449498, checked in by Joel Sherrill <joel.sherrill@…>, on 01/17/02 at 21:47:47

2001-01-17 Joel Sherrill <joel@…>

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