summaryrefslogtreecommitdiffstats
path: root/c-user/barrier/background.rst
blob: 7a42d97fd144571fca0af04cc524fc855999681d (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
.. SPDX-License-Identifier: CC-BY-SA-4.0

.. Copyright (C) 1988, 2018 On-Line Applications Research Corporation (OAR)

Background
==========

A barrier can be viewed as a gate at which tasks wait until the gate is opened.
This has many analogies in the real world.  Horses and other farm animals may
approach a closed gate and gather in front of it, waiting for someone to open
the gate so they may proceed.  Similarly, ticket holders gather at the gates of
arenas before concerts or sporting events waiting for the arena personnel to
open the gates so they may enter.

Barriers are useful during application initialization.  Each application task
can perform its local initialization before waiting for the application as a
whole to be initialized.  Once all tasks have completed their independent
initializations, the "application ready" barrier can be released.

Automatic Versus Manual Barriers
--------------------------------

Just as with a real-world gate, barriers may be configured to be manually
opened or automatically opened.  All tasks calling the ``rtems_barrier_wait``
directive will block until a controlling task invokes
the ``rtems_barrier_release`` directive.

Automatic barriers are created with a limit to the number of tasks which may
simultaneously block at the barrier.  Once this limit is reached, all of the
tasks are released.  For example, if the automatic limit is ten tasks, then the
first nine tasks calling the ``rtems_barrier_wait`` directive will block.  When
the tenth task calls the ``rtems_barrier_wait`` directive, the nine blocked
tasks will be released and the tenth task returns to the caller without
blocking.

Building a Barrier Attribute Set
--------------------------------

In general, an attribute set is built by a bitwise OR of the desired attribute
components.  The following table lists the set of valid barrier attributes:

``RTEMS_BARRIER_AUTOMATIC_RELEASE``
  automatically release the barrier when the configured number of tasks are
  blocked

``RTEMS_BARRIER_MANUAL_RELEASE``
  only release the barrier when the application invokes the
  ``rtems_barrier_release`` directive.  (default)

.. note::

  Barriers only support FIFO blocking order because all waiting tasks are
  released as a set.  Thus the released tasks will all become ready to execute
  at the same time and compete for the processor based upon their priority.

Attribute values are specifically designed to be mutually exclusive, therefore
bitwise OR and addition operations are equivalent as long as each attribute
appears exactly once in the component list.  An attribute listed as a default
is not required to appear in the attribute list, although it is a good
programming practice to specify default attributes.  If all defaults are
desired, the attribute ``RTEMS_DEFAULT_ATTRIBUTES`` should be specified on this
call.

This example demonstrates the attribute_set parameter needed to create a
barrier with the automatic release policy.  The ``attribute_set`` parameter
passed to the ``rtems_barrier_create`` directive will be
``RTEMS_BARRIER_AUTOMATIC_RELEASE``.  In this case, the user must also specify
the ``maximum_waiters`` parameter.