source: rtems/doc/user/event.t @ a3a7527

4.104.114.84.95
Last change on this file since a3a7527 was a3a7527, checked in by Joel Sherrill <joel.sherrill@…>, on Mar 27, 1998 at 1:04:02 PM

Attempting to add variable so that in C all constants start with RTEMS_
and all directives start with rtems_.

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