source: rtems/doc/user/barrier.t @ a570a14

4.8
Last change on this file since a570a14 was a570a14, checked in by Joel Sherrill <joel.sherrill@…>, on Jul 15, 2008 at 9:49:59 PM

2008-07-15 Joel Sherrill <joel.sherrill@…>

  • user/barrier.t, user/clock.t, user/dpmem.t, user/msg.t, user/part.t, user/region.t, user/rtmon.t, user/sem.t, user/task.t, user/timer.t: Correct documentation typos noticed and thankfully reported by Fabrício de Novaes Kucinskis <fabricio@…>
  • Property mode set to 100644
File size: 15.0 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2007.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Barrier Manager
10
11@cindex barrier
12
13@section Introduction
14
15The barrier manager provides a unique synchronization
16capability which can be used to have a set of tasks block
17and be unblocked as a set.  The directives provided by the
18barrier manager are:
19
20@itemize @bullet
21@item @code{@value{DIRPREFIX}barrier_create} -  Create a barrier
22@item @code{@value{DIRPREFIX}barrier_ident} - Get ID of a barrier
23@item @code{@value{DIRPREFIX}barrier_delete} - Delete a barrier
24@item @code{@value{DIRPREFIX}barrier_wait} - Wait at a barrier
25@item @code{@value{DIRPREFIX}barrier_release} - Release a barrier
26@end itemize
27
28@section Background
29
30A barrier can be viewed as a gate at which tasks wait until
31the gate is opened.  This has many analogies in the real world.
32Horses and other farm animals may approach a closed gate and
33gather in front of it, waiting for someone to open the gate so
34they may proceed.  Similarly, cticket holders gather at the gates
35of arenas before concerts or sporting events waiting for the
36arena personnel to open the gates so they may enter.
37
38Barriers are useful during application initialization.  Each
39application task can perform its local initialization before
40waiting for the application as a whole to be initialized.  Once
41all tasks have completed their independent initializations,
42the "application ready" barrier can be released.
43
44@subsection Automatic Versus Manual Barriers
45
46Just as with a real-world gate, barriers may be configured to
47be manually opened or automatically opened.  All tasks
48calling the @code{@value{DIRPREFIX}barrier_wait} directive
49will block until a controlling task invokes the
50@code{@value{DIRPREFIX}barrier_release} directive.
51
52Automatic barriers are created with a limit to the number of
53tasks which may simultaneously block at the barrier.  Once
54this limit is reached, all of the tasks are released.  For
55example, if the automatic limit is ten tasks, then the first
56nine tasks calling the @code{@value{DIRPREFIX}barrier_wait} directive
57will block.  When the tenth task calls the
58@code{@value{DIRPREFIX}barrier_wait} directive, the nine
59blocked tasks will be released and the tenth task returns
60to the caller without blocking.
61
62@subsection Building a Barrier Attribute Set
63
64In general, an attribute set is built by a bitwise OR
65of the desired attribute components.  The following table lists
66the set of valid barrier attributes:
67
68@itemize @bullet
69
70@item @code{@value{RPREFIX}BARRIER_AUTOMATIC_RELEASE} - automatically
71release the barrier when the configured number of tasks are blocked
72
73@item @code{@value{RPREFIX}BARRIER_MANUAL_RELEASE} - only release
74the barrier when the application invokes the
75@code{@value{DIRPREFIX}barrier_release} directive.  (default)
76
77@end itemize
78
79@b{NOTE}: Barriers only support FIFO blocking order because all
80waiting tasks are released as a set.  Thus the released tasks
81will all become ready to execute at the same time and compete
82for the processor based upon their priority.
83
84Attribute values are specifically designed to be
85mutually exclusive, therefore bitwise OR and addition operations
86are equivalent as long as each attribute appears exactly once in
87the component list.  An attribute listed as a default is not
88required to appear in the attribute list, although it is a good
89programming practice to specify default attributes.  If all
90defaults are desired, the attribute
91@code{@value{RPREFIX}DEFAULT_ATTRIBUTES} should be
92specified on this call.
93
94This example demonstrates the attribute_set parameter needed to create a
95barrier with the automatic release policy.  The
96@code{attribute_set} parameter passed to the
97@code{@value{DIRPREFIX}barrier_create} directive will be
98@code{@value{RPREFIX}BARRIER_AUTOMATIC_RELEASE}.  In this case, the
99user must also specify the @i{maximum_waiters} parameter.
100
101@section Operations
102
103@subsection Creating a Barrier
104
105The @code{@value{DIRPREFIX}barrier_create} directive creates
106a barrier with a user-specified name and the desired attributes.
107RTEMS allocates a Barrier Control Block (BCB) from the BCB free list.
108This data structure is used by RTEMS to manage the newly created
109barrier.  Also, a unique barrier ID is generated and returned to
110the calling task.
111
112@subsection Obtaining Barrier IDs
113
114When a barrier is created, RTEMS generates a unique
115barrier ID and assigns it to the created barrier until it is
116deleted.  The barrier ID may be obtained by either of two
117methods.  First, as the result of an invocation of the
118@code{@value{DIRPREFIX}barrier_create} directive, the
119barrier ID is stored in a user provided location.  Second,
120the barrier ID may be obtained later using the
121@code{@value{DIRPREFIX}barrier_ident} directive.  The barrier ID is
122used by other barrier manager directives to access this
123barrier.
124
125@subsection Waiting at a Barrier
126
127The @code{@value{DIRPREFIX}barrier_wait} directive is used to wait at
128the specified barrier.  Since a barrier is, by definition, never immediately,
129the task may wait forever for the barrier to be released or it may
130specify a timeout.  Specifying a timeout limits the interval the task will
131wait before returning with an error status code.
132
133If the barrier is configured as automatic and there are already
134one less then the maximum number of waiters, then the call will
135unblock all tasks waiting at the barrier and the caller will
136return immediately.
137
138When the task does wait to acquire the barrier, then it
139is placed in the barrier's task wait queue in FIFO order.
140All tasks waiting on a barrier are returned an error
141code when the barrier is deleted.
142
143@subsection Releasing a Barrier
144
145The @code{@value{DIRPREFIX}barrier_release} directive is used to release
146the specified barrier.  When the @code{@value{DIRPREFIX}barrier_release}
147is invoked, all tasks waiting at the barrier are immediately made ready
148to execute and begin to compete for the processor to execute.
149
150@subsection Deleting a Barrier
151
152The @code{@value{DIRPREFIX}barrier_delete} directive removes a barrier
153from the system and frees its control block.  A barrier can be
154deleted by any local task that knows the barrier's ID.  As a
155result of this directive, all tasks blocked waiting for the
156barrier to be released, will be readied and returned a status code which
157indicates that the barrier was deleted.  Any subsequent
158references to the barrier's name and ID are invalid.
159
160@section Directives
161
162This section details the barrier manager's
163directives.  A subsection is dedicated to each of this manager's
164directives and describes the calling sequence, related
165constants, usage, and status codes.
166
167@c
168@c
169@c
170@page
171@subsection BARRIER_CREATE - Create a barrier
172
173@cindex create a barrier
174
175@subheading CALLING SEQUENCE:
176
177@ifset is-C
178@findex rtems_barrier_create
179@example
180rtems_status_code rtems_barrier_create(
181  rtems_name           name,
182  rtems_attribute      attribute_set,
183  uint32_t             maximum_waiters,
184  rtems_id            *id
185);
186@end example
187@end ifset
188
189@ifset is-Ada
190@example
191procedure Barrier_Create (
192   Name            : in     RTEMS.Name;
193   Attribute_Set   : in     RTEMS.Attribute;
194   Maximum_Waiters : in     RTEMS.Unsigned32;
195   ID              :    out RTEMS.ID;
196   Result          :    out RTEMS.Status_Codes
197);
198@end example
199@end ifset
200
201@subheading DIRECTIVE STATUS CODES:
202@code{@value{RPREFIX}SUCCESSFUL} - barrier created successfully@*
203@code{@value{RPREFIX}INVALID_NAME} - invalid barrier name@*
204@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@*
205@code{@value{RPREFIX}TOO_MANY} - too many barriers created@
206
207@subheading DESCRIPTION:
208
209This directive creates a barrier which resides on
210the local node. The created barrier has the user-defined name
211specified in @code{name} and the initial count specified in @code{count}.  For
212control and maintenance of the barrier, RTEMS allocates and
213initializes a BCB.  The RTEMS-assigned barrier id is returned
214in @code{id}.  This barrier id is used with other barrier related
215directives to access the barrier.
216
217@code{@value{RPREFIX}BARRIER_MANUAL_RELEASE} - only release
218
219Specifying @code{@value{RPREFIX}BARRIER_AUTOMATIC_RELEASE} in
220@code{attribute_set} causes tasks calling the
221@code{@value{DIRPREFIX}barrier_wait} directive to block until
222there are @code{maximum_waiters - 1} tasks waiting at the barrier.
223When the @code{maximum_waiters} task invokes the
224@code{@value{DIRPREFIX}barrier_wait} directive, the previous
225@code{maximum_waiters - 1} tasks are automatically released
226and the caller returns.
227
228In contrast, when the @code{@value{RPREFIX}BARRIER_MANUAL_RELEASE}
229attribute is specified, there is no limit on the number of
230tasks that will block at the barrier. Only when the
231@code{@value{DIRPREFIX}barrier_release} directive is invoked,
232are the tasks waiting at the barrier unblocked.
233
234@subheading NOTES:
235
236This directive will not cause the calling task to be preempted.
237
238The following barrier attribute constants are defined by RTEMS:
239
240@itemize @bullet
241
242@item @code{@value{RPREFIX}BARRIER_AUTOMATIC_RELEASE} - automatically
243release the barrier when the configured number of tasks are blocked
244
245@item @code{@value{RPREFIX}BARRIER_MANUAL_RELEASE} - only release
246the barrier when the application invokes the
247@code{@value{DIRPREFIX}barrier_release} directive.  (default)
248
249@end itemize
250
251@c
252@c
253@c
254@page
255@subsection BARRIER_IDENT - Get ID of a barrier
256
257@cindex get ID of a barrier
258@cindex obtain ID of a barrier
259
260@subheading CALLING SEQUENCE:
261
262@ifset is-C
263@findex rtems_barrier_ident
264@example
265rtems_status_code rtems_barrier_ident(
266  rtems_name        name,
267  rtems_id         *id
268);
269@end example
270@end ifset
271
272@ifset is-Ada
273@example
274procedure Barrier_Ident (
275   Name   : in     RTEMS.Name;
276   ID     :    out RTEMS.ID;
277   Result :    out RTEMS.Status_Codes
278);
279@end example
280@end ifset
281
282@subheading DIRECTIVE STATUS CODES:
283@code{@value{RPREFIX}SUCCESSFUL} - barrier identified successfully@*
284@code{@value{RPREFIX}INVALID_NAME} - barrier name not found@*
285@code{@value{RPREFIX}INVALID_NODE} - invalid node id
286
287@subheading DESCRIPTION:
288
289This directive obtains the barrier id associated
290with the barrier name.  If the barrier name is not unique,
291then the barrier id will match one of the barriers with that
292name.  However, this barrier id is not guaranteed to
293correspond to the desired barrier.  The barrier id is used
294by other barrier related directives to access the barrier.
295
296@subheading NOTES:
297
298This directive will not cause the running task to be
299preempted.
300
301@c
302@c
303@c
304@page
305@subsection BARRIER_DELETE - Delete a barrier
306
307@cindex delete a barrier
308
309@subheading CALLING SEQUENCE:
310
311@ifset is-C
312@findex rtems_barrier_delete
313@example
314rtems_status_code rtems_barrier_delete(
315  rtems_id id
316);
317@end example
318@end ifset
319
320@ifset is-Ada
321@example
322procedure Barrier_Delete (
323   ID     : in     RTEMS.ID;
324   Result :    out RTEMS.Status_Codes
325);
326@end example
327@end ifset
328
329@subheading DIRECTIVE STATUS CODES:
330@code{@value{RPREFIX}SUCCESSFUL} -  barrier deleted successfully@*
331@code{@value{RPREFIX}INVALID_ID} - invalid barrier id@
332
333@subheading DESCRIPTION:
334
335This directive deletes the barrier specified by @code{id}.
336All tasks blocked waiting for the barrier to be released will be
337readied and returned a status code which indicates that the
338barrier was deleted.  The BCB for this barrier is reclaimed
339by RTEMS.
340
341@subheading NOTES:
342
343The calling task will be preempted if it is enabled
344by the task's execution mode and a higher priority local task is
345waiting on the deleted barrier.  The calling task will NOT be
346preempted if all of the tasks that are waiting on the barrier
347are remote tasks.
348
349The calling task does not have to be the task that
350created the barrier.  Any local task that knows the barrier
351id can delete the barrier.
352
353@c
354@c Barrier Obtain
355@c
356@page
357@subsection BARRIER_OBTAIN - Acquire a barrier
358
359@cindex obtain a barrier
360@cindex lock a barrier
361
362@subheading CALLING SEQUENCE:
363
364@ifset is-C
365@findex rtems_barrier_wait
366@example
367rtems_status_code rtems_barrier_wait(
368  rtems_id         id,
369  rtems_interval   timeout
370);
371@end example
372@end ifset
373
374@ifset is-Ada
375@example
376procedure Barrier_Wait (
377   ID         : in     RTEMS.ID;
378   Timeout    : in     RTEMS.Interval;
379   Result     :    out RTEMS.Status_Codes
380);
381@end example
382@end ifset
383
384@subheading DIRECTIVE STATUS CODES:
385@code{@value{RPREFIX}SUCCESSFUL} - barrier obtained successfully@*
386@code{@value{RPREFIX}UNSATISFIED} - barrier not available@*
387@code{@value{RPREFIX}TIMEOUT} - timed out waiting for barrier@*
388@code{@value{RPREFIX}OBJECT_WAS_DELETED} - barrier deleted while waiting@*
389@code{@value{RPREFIX}INVALID_ID} - invalid barrier id
390
391@subheading DESCRIPTION:
392
393This directive acquires the barrier specified by
394id.  The @code{@value{RPREFIX}WAIT} and @code{@value{RPREFIX}NO_WAIT}
395components of the options parameter indicate whether the calling task
396wants to wait for the barrier to become available or return immediately
397if the barrier is not currently available.  With either
398@code{@value{RPREFIX}WAIT} or @code{@value{RPREFIX}NO_WAIT},
399if the current barrier count is positive, then it is
400decremented by one and the barrier is successfully acquired by
401returning immediately with a successful return code.
402
403Conceptually, the calling task should always be thought
404of as blocking when it makes this call and being unblocked when
405the barrier is released.  If the barrier is configured for
406manual release, this rule of thumb will always be valid.
407If the barrier is configured for automatic release, all callers
408will block except for the one which is the Nth task which trips
409the automatic release condition.
410
411The timeout parameter specifies the maximum interval the calling task is
412willing to be blocked waiting for the barrier.  If it is set to
413@code{@value{RPREFIX}NO_TIMEOUT}, then the calling task will wait forever. 
414If the barrier is available or the @code{@value{RPREFIX}NO_WAIT} option
415component is set, then timeout is ignored.
416
417@subheading NOTES:
418The following barrier acquisition option constants are defined by RTEMS:
419
420@itemize @bullet
421@item @code{@value{RPREFIX}WAIT} - task will wait for barrier (default)
422@item @code{@value{RPREFIX}NO_WAIT} - task should not wait
423@end itemize
424
425A clock tick is required to support the timeout functionality of
426this directive.
427
428@c
429@c Release Barrier
430@c
431@page
432@subsection BARRIER_RELEASE - Release a barrier
433
434@cindex wait at a barrier
435@cindex release a barrier
436
437@subheading CALLING SEQUENCE:
438
439@ifset is-C
440@findex rtems_barrier_release
441@example
442rtems_status_code rtems_barrier_release(
443  rtems_id  id,
444  uint32_t *released
445);
446@end example
447@end ifset
448
449@ifset is-Ada
450@example
451procedure Barrier_Release (
452   ID       : in     RTEMS.ID;
453   Released :    out RTEMS.Unsigned32;
454   Result   :    out RTEMS.Status_Codes
455);
456@end example
457@end ifset
458
459@subheading DIRECTIVE STATUS CODES:
460@code{@value{RPREFIX}SUCCESSFUL} - barrier released successfully@*
461@code{@value{RPREFIX}INVALID_ID} - invalid barrier id@*
462
463@subheading DESCRIPTION:
464
465This directive releases the barrier specified by id.
466All tasks waiting at the barrier will be unblocked.
467If the running task's preemption mode is enabled and one of
468the unblocked tasks has a higher priority than the running task.
469
470@subheading NOTES:
471
472The calling task may be preempted if it causes a
473higher priority task to be made ready for execution.
Note: See TracBrowser for help on using the repository browser.