source: rtems-docs/c_user/barrier_manager.rst @ 8ef6ea8

4.115
Last change on this file since 8ef6ea8 was 8ef6ea8, checked in by Chris Johns <chrisj@…>, on 01/27/16 at 06:50:19

Clean ups.

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