Barrier Manager

The Barrier Manager provides a unique synchronization capability which can be used to have a set of tasks block and be unblocked as a set. More...

Functions
rtems_status_code	rtems_barrier_create (rtems_name name, rtems_attribute attribute_set, uint32_t maximum_waiters, rtems_id *id)
	Creates a barrier.
rtems_status_code	rtems_barrier_ident (rtems_name name, rtems_id *id)
	Identifies a barrier by the object name.
rtems_status_code	rtems_barrier_delete (rtems_id id)
	Deletes the barrier.
rtems_status_code	rtems_barrier_wait (rtems_id id, rtems_interval timeout)
	Waits at the barrier.
rtems_status_code	rtems_barrier_release (rtems_id id, uint32_t *released)
	Releases the barrier.

Detailed Description

The Barrier Manager provides a unique synchronization capability which can be used to have a set of tasks block and be unblocked as a set.

Function Documentation

rtems_barrier_create()

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

Creates a barrier.

Parameters

name	is the object name of the barrier.
attribute_set	is the attribute set of the barrier.
maximum_waiters	is the maximum count of waiters on an automatic release barrier.
id	is the pointer to an rtems_id object. When the directive call is successful, the identifier of the created barrier will be stored in this object.

This directive creates a barrier which resides on the local node. The barrier has the user-defined object name specified in name and the initial count specified in attribute_set. The assigned object identifier is returned in id. This identifier is used to access the barrier with other barrier related directives.

The attribute set specified in attribute_set is built through a bitwise or of the attribute constants described below. Not all combinations of attributes are allowed. Some attributes are mutually exclusive. If mutually exclusive attributes are combined, the behaviour is undefined. Attributes not mentioned below are not evaluated by this directive and have no effect. Default attributes can be selected by using the RTEMS_DEFAULT_ATTRIBUTES constant.

The barrier class is selected by the mutually exclusive RTEMS_BARRIER_MANUAL_RELEASE and RTEMS_BARRIER_AUTOMATIC_RELEASE attributes.

• The manual release class is the default and can be emphasized through use of the RTEMS_BARRIER_MANUAL_RELEASE attribute. For this class, 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.
• The automatic release class is selected by the RTEMS_BARRIER_AUTOMATIC_RELEASE attribute. For this class, tasks calling the rtems_barrier_wait() directive will block until there are maximum_waiters minus one 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.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_NAME	The name parameter was invalid.
RTEMS_INVALID_ADDRESS	The id parameter was NULL.
RTEMS_INVALID_NUMBER	The maximum_waiters parameter was 0 for an automatic release barrier.
RTEMS_TOO_MANY	There was no inactive object available to create a barrier. The number of barriers available to the application is configured through the CONFIGURE_MAXIMUM_BARRIERS application configuration option.

Notes

For control and maintenance of the barrier, RTEMS allocates a BCB from the local BCB free pool and initializes it.

Constraints

The following constraints apply to this directive:

• The directive may be called from within device driver initialization context.
• The directive may be called from within task context.
• The directive may obtain and release the object allocator mutex. This may cause the calling task to be preempted.
• The number of barriers available to the application is configured through the CONFIGURE_MAXIMUM_BARRIERS application configuration option.
• Where the object class corresponding to the directive is configured to use unlimited objects, the directive may allocate memory from the RTEMS Workspace.

rtems_barrier_delete()

rtems_status_code rtems_barrier_delete

(

rtems_id

id

)

Deletes the barrier.

Parameters

id	is the barrier identifier.

This directive deletes the barrier specified by id. All tasks blocked waiting for the barrier to be released will be readied and returned a status code which indicates that the barrier was deleted.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no barrier associated with the identifier specified by id.

Notes

The BCB for the deleted barrier is reclaimed by RTEMS.

Constraints

The following constraints apply to this directive:

• The directive may be called from within device driver initialization context.
• The directive may be called from within task context.
• The directive may obtain and release the object allocator mutex. This may cause the calling task to be preempted.
• The calling task does not have to be the task that created the object. Any local task that knows the object identifier can delete the object.
• Where the object class corresponding to the directive is configured to use unlimited objects, the directive may free memory to the RTEMS Workspace.

rtems_barrier_ident()

rtems_status_code rtems_barrier_ident	(	rtems_name	name,
		rtems_id *	id
	)

Identifies a barrier by the object name.

Parameters

	name	is the object name to look up.
[out]	id	is the pointer to an rtems_id object. When the directive call is successful, the object identifier of an object with the specified name will be stored in this object.

This directive obtains a barrier identifier associated with the barrier name specified in name.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ADDRESS	The id parameter was NULL.
RTEMS_INVALID_NAME	The name parameter was 0.
RTEMS_INVALID_NAME	There was no object with the specified name on the local node.

Notes

If the barrier name is not unique, then the barrier identifier will match the first barrier with that name in the search order. However, this barrier identifier is not guaranteed to correspond to the desired barrier.

The objects are searched from lowest to the highest index. Only the local node is searched.

The barrier identifier is used with other barrier related directives to access the barrier.

Constraints

The following constraints apply to this directive:

• The directive may be called from within any runtime context.
• The directive will not cause the calling task to be preempted.

rtems_barrier_release()

rtems_status_code rtems_barrier_release	(	rtems_id	id,
		uint32_t *	released
	)

Releases the barrier.

Parameters

	id	is the barrier identifier.
[out]	released	is the pointer to an uint32_t object. When the directive call is successful, the number of released tasks will be stored in this object.

This directive releases the barrier specified by id. All tasks waiting at the barrier will be unblocked. The number of released tasks will be returned in released.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ADDRESS	The released parameter was NULL.
RTEMS_INVALID_ID	There was no barrier associated with the identifier specified by id.

Constraints

The following constraints apply to this directive:

• The directive may be called from within interrupt context.
• The directive may be called from within task context.
• The directive may unblock a task. This may cause the calling task to be preempted.

rtems_barrier_wait()

rtems_status_code rtems_barrier_wait	(	rtems_id	id,
		rtems_interval	timeout
	)

Waits at the barrier.

Parameters

id	is the barrier identifier.
timeout	is the timeout in clock ticks. Use RTEMS_NO_TIMEOUT to wait potentially forever.

This directive waits at the barrier specified by id. The timeout parameter defines how long the calling task is willing to wait. Use RTEMS_NO_TIMEOUT to wait potentially forever, otherwise set a timeout interval in clock ticks.

Conceptually, the calling task should always be thought of as blocking when it makes this call and being unblocked when the barrier is released. If the barrier is configured for manual release, this rule of thumb will always be valid. If the barrier is configured for automatic release, all callers will block except for the one which trips the automatic release condition.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no barrier associated with the identifier specified by id.
RTEMS_TIMEOUT	The timeout happened while the calling task was waiting at the barrier.
RTEMS_OBJECT_WAS_DELETED	The barrier was deleted while the calling task was waiting at the barrier.

Notes

For automatic release barriers, the maximum count of waiting tasks is defined during barrier creation, see rtems_barrier_create().

Constraints

The following constraints apply to this directive:

• The directive may be called from within task context.
• The timeout functionality of the directive requires a clock tick.