RTEMS 4.8.0 On-Line Library

Barrier Manager BARRIER_CREATE - Create a barrier

RTEMS C User's Guide

20.4.1: BARRIER_CREATE - Create a barrier

CALLING SEQUENCE:

rtems_status_code rtems_barrier_create(
  rtems_name           name,
  rtems_attribute      attribute_set,
  uint32_t             maximum_waiters,
  rtems_id            *id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL - barrier created successfully
RTEMS_INVALID_NAME - invalid task name
RTEMS_INVALID_ADDRESS - id is NULL
RTEMS_TOO_MANY - too many barriers created@

DESCRIPTION:

This directive creates a barrier which resides on the local node. The created barrier has the user-defined name specified in name and the initial count specified in count. For control and maintenance of the barrier, RTEMS allocates and initializes a BCB. The RTEMS-assigned barrier id is returned in id. This barrier id is used with other barrier related directives to access the barrier.

RTEMS_BARRIER_MANUAL_RELEASE - only release

Specifying RTEMS_BARRIER_AUTOMATIC_RELEASE in attribute_set causes tasks calling the rtems_barrier_wait directive to block until there are maximum_waiters - 1 tasks waiting at the barrier. When the maximum_waiters task invokes the rtems_barrier_wait directive, the previous maximum_waiters - 1 tasks are automatically released and the caller returns.

In contrast, when the RTEMS_BARRIER_MANUAL_RELEASE attribute is specified, there is no limit on the number of tasks that will block at the barrier. Only when the rtems_barrier_release directive is invoked, are the tasks waiting at the barrier unblocked.

NOTES:

This directive will not cause the calling task to be preempted.

The following barrier attribute constants are defined by RTEMS:

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)

RTEMS C User's Guide