source: rtems/doc/user/event.t @ 87ed029

4.104.114.84.95
Last change on this file since 87ed029 was 87ed029, checked in by Joel Sherrill <joel.sherrill@…>, on 04/02/98 at 16:18:26

Added "findex" for all directive pages but it turns out that this
blows up both makeinfo and texi2dvi. So I have commented them out.

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