Barrier Handler

This handler encapsulates functionality which provides the foundation Barrier services used in all of the APIs supported by RTEMS. More...

Collaboration diagram for Barrier Handler:

Files
file	corebarrier.c
	Initialize CORE Barrier.
file	corebarrierrelease.c
	Manually releases the Barrier.
file	corebarrierwait.c
	Wait For The Barrier.

Data Structures
struct	CORE_barrier_Attributes
	The following defines the control block used to manage the attributes of each barrier. More...
struct	CORE_barrier_Control
	The following defines the control block used to manage each barrier. More...

Macros
#define	CORE_BARRIER_STATUS_LAST   CORE_BARRIER_TIMEOUT
	Core barrier last status value. More...
#define	_CORE_barrier_Flush(_the_barrier, _remote_extract_callout, _status)
	This routine assists in the deletion of a barrier by flushing the associated wait queue. More...

Typedefs
typedef void(*	CORE_barrier_API_mp_support_callout) (Thread_Control *, Objects_Id)
	The following type defines the callout which the API provides to support global/multiprocessor operations on barriers.

Enumerations
enum	CORE_barrier_Disciplines { CORE_BARRIER_AUTOMATIC_RELEASE, CORE_BARRIER_MANUAL_RELEASE }
	Flavors of barriers. More...
enum	CORE_barrier_Status { CORE_BARRIER_STATUS_SUCCESSFUL, CORE_BARRIER_STATUS_AUTOMATICALLY_RELEASED, CORE_BARRIER_WAS_DELETED, CORE_BARRIER_TIMEOUT }
	Core Barrier handler return statuses. More...

Functions
void	_CORE_barrier_Initialize (CORE_barrier_Control *the_barrier, CORE_barrier_Attributes *the_barrier_attributes)
	Initialize core barrier. More...
RTEMS_INLINE_ROUTINE void	_CORE_barrier_Destroy (CORE_barrier_Control *the_barrier)
void	_CORE_barrier_Wait (CORE_barrier_Control *the_barrier, Thread_Control *executing, Objects_Id id, bool wait, Watchdog_Interval timeout, CORE_barrier_API_mp_support_callout api_barrier_mp_support)
	Wait for the barrier. More...
uint32_t	_CORE_barrier_Release (CORE_barrier_Control *the_barrier, Objects_Id id, CORE_barrier_API_mp_support_callout api_barrier_mp_support)
	Manually release the barrier. More...
RTEMS_INLINE_ROUTINE bool	_CORE_barrier_Is_automatic (CORE_barrier_Attributes *the_attribute)
	This function returns true if the automatic release attribute is enabled in the attribute_set and false otherwise. More...
RTEMS_INLINE_ROUTINE uint32_t	_CORE_barrier_Get_number_of_waiting_threads (CORE_barrier_Control *the_barrier)
	This routine returns the number of threads currently waiting at the barrier. More...

Detailed Description

This handler encapsulates functionality which provides the foundation Barrier services used in all of the APIs supported by RTEMS.

Macro Definition Documentation

_CORE_barrier_Flush

#define _CORE_barrier_Flush	(		_the_barrier,
			_remote_extract_callout,
			_status
	)

Value:

_Thread_queue_Flush( \
    &((_the_barrier)->Wait_queue), \
    (_remote_extract_callout), \
    (_status) \
  )

This routine assists in the deletion of a barrier by flushing the associated wait queue.

Parameters

[in]	_the_barrier	is the barrier to flush
[in]	_remote_extract_callout	is the routine to invoke if the thread unblocked is remote
[in]	_status	is the status to be returned to the unblocked thread

CORE_BARRIER_STATUS_LAST

#define CORE_BARRIER_STATUS_LAST   CORE_BARRIER_TIMEOUT

Core barrier last status value.

This is the last status value.

Referenced by _Barrier_Translate_core_barrier_return_code(), and _POSIX_Barrier_Translate_core_barrier_return_code().

Enumeration Type Documentation

CORE_barrier_Disciplines

enum CORE_barrier_Disciplines

Flavors of barriers.

Enumerator
CORE_BARRIER_AUTOMATIC_RELEASE	This specifies that the barrier will automatically release when the user specified number of threads have arrived at the barrier.
CORE_BARRIER_MANUAL_RELEASE	This specifies that the user will have to manually release the barrier in order to release the waiting threads.

CORE_barrier_Status

enum CORE_barrier_Status

Core Barrier handler return statuses.

Enumerator
CORE_BARRIER_STATUS_SUCCESSFUL	This status indicates that the operation completed successfully.
CORE_BARRIER_STATUS_AUTOMATICALLY_RELEASED	This status indicates that the barrier is configured for automatic release and the caller tripped the automatic release. The caller thus did not block.
CORE_BARRIER_WAS_DELETED	This status indicates that the thread was blocked waiting for an operation to complete and the barrier was deleted.
CORE_BARRIER_TIMEOUT	This status indicates that the calling task was willing to block but the operation was unable to complete within the time allotted because the resource never became available.

Function Documentation

_CORE_barrier_Get_number_of_waiting_threads()

RTEMS_INLINE_ROUTINE uint32_t _CORE_barrier_Get_number_of_waiting_threads

(

CORE_barrier_Control *

the_barrier

)

This routine returns the number of threads currently waiting at the barrier.

Parameters

[in]

the_barrier

is the barrier to obtain the number of blocked threads for

Returns

the current count of this barrier

References CORE_barrier_Control::number_of_waiting_threads.

_CORE_barrier_Initialize()

void _CORE_barrier_Initialize	(	CORE_barrier_Control *	the_barrier,
		CORE_barrier_Attributes *	the_barrier_attributes
	)

Initialize core barrier.

This routine initializes the barrier based on the parameters passed.

Parameters

[in]	the_barrier	is the barrier to initialize
[in]	the_barrier_attributes	define the behavior of this instance

References _Thread_queue_Initialize(), CORE_barrier_Control::Attributes, CORE_barrier_Control::number_of_waiting_threads, and CORE_barrier_Control::Wait_queue.

Referenced by rtems_barrier_create().

_CORE_barrier_Is_automatic()

RTEMS_INLINE_ROUTINE bool _CORE_barrier_Is_automatic

(

CORE_barrier_Attributes *

the_attribute

)

This function returns true if the automatic release attribute is enabled in the attribute_set and false otherwise.

Parameters

[in]

the_attribute

is the attribute set to test

Returns

true if the priority attribute is enabled

References CORE_BARRIER_AUTOMATIC_RELEASE, and CORE_barrier_Attributes::discipline.

_CORE_barrier_Release()

uint32_t _CORE_barrier_Release	(	CORE_barrier_Control *	the_barrier,
		Objects_Id	id,
		CORE_barrier_API_mp_support_callout	api_barrier_mp_support
	)

Manually release the barrier.

This routine manually releases the barrier. All of the threads waiting for the barrier will be readied.

Parameters

[in]	the_barrier	is the barrier to surrender
[in]	id	is the id of the object for a remote unblock
[in]	api_barrier_mp_support	is the routine to invoke if the thread unblocked is remote

Return values

the	number of unblocked threads

References _Objects_Is_local_id(), _Thread_queue_Dequeue(), Objects_Control::id, CORE_barrier_Control::number_of_waiting_threads, Thread_Control::Object, and CORE_barrier_Control::Wait_queue.

_CORE_barrier_Wait()

void _CORE_barrier_Wait	(	CORE_barrier_Control *	the_barrier,
		Thread_Control *	executing,
		Objects_Id	id,
		bool	wait,
		Watchdog_Interval	timeout,
		CORE_barrier_API_mp_support_callout	api_barrier_mp_support
	)

Wait for the barrier.

This routine wait for the barrier to be released. If the barrier is set to automatic and this is the appropriate thread, then it returns immediately. Otherwise, the calling thread is blocked until the barrier is released.

Parameters

[in]	the_barrier	is the barrier to wait for
[in,out]	executing	The currently executing thread.
[in]	id	is the id of the object being waited upon
[in]	wait	is true if the calling thread is willing to wait
[in]	timeout	is the number of ticks the calling thread is willing to wait if wait is true.
[in]	api_barrier_mp_support	is the routine to invoke if the thread unblocked is remote

Note

Status is returned via the thread control block.