source: rtems-docs/c-user/barrier_manager.rst @ 2abceef

4.11
Last change on this file since 2abceef was 2abceef, checked in by Joel Sherrill <joel@…>, on 10/05/18 at 21:44:26

barrier_manager.rst: Fix Barrier Wait Section Title

closes #3541.

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