Barriers

KOS barrier API for kernel threads More...

Files
file	barrier.h
	Thread barriers.

Data Structures
union	thd_barrier_t
	Thread barrier type. More...

Macros
#define	THD_BARRIER_SERIAL_THREAD   0x7fffffff
	Constant returned to one thread from pthread_barrier_wait().
#define	THD_BARRIER_SIZE   64
	Size of a thread barrier, in bytes.

Functions
int	thd_barrier_init (thd_barrier_t *__RESTRICT barrier, const void *__RESTRICT attr, unsigned count)
	Initialize a thread barrier.
int	thd_barrier_destroy (thd_barrier_t *barrier)
	Destroy a thread barrier.
int	thd_barrier_wait (thd_barrier_t *barrier)
	Wait on a thread barrier.

Detailed Description

KOS barrier API for kernel threads

Barriers are a type of synchronization method which halt execution for group of threads until a certain number of them have reached the barrier.

Macro Definition Documentation

THD_BARRIER_SERIAL_THREAD

#define THD_BARRIER_SERIAL_THREAD   0x7fffffff

Constant returned to one thread from pthread_barrier_wait().

A single (unspecified) thread will be returned this value after successfully waiting on a barrier, with all other threads being returned a 0. This is useful for selecting one thread to perform any cleanup work associated with the barrier (or other serial work that must be performed).

THD_BARRIER_SIZE

#define THD_BARRIER_SIZE   64

Size of a thread barrier, in bytes.

Function Documentation

thd_barrier_destroy()

int thd_barrier_destroy

(

thd_barrier_t *

barrier

)

Destroy a thread barrier.

This function destroys a thread barrier, releasing any resources associated with the barrier. Subsequent use of the barrier is results in undefined behavior unless it is later re-initialized with thd_barrier_init().

Parameters

barrier

The barrier to destroy.

Returns

0 on success, non-zero error code on failure

Error Conditions:

EBUSY - A destroy operation is already in progress on barrier
EINVAL - NULL was passed for barrier
EINVAL - An already destroyed barrier was passed in
EPERM - Function was called in an interrupt context

Note

This function may block if a wait operation is currently in progress on the specified barrier.

thd_barrier_init()

int thd_barrier_init	(	thd_barrier_t *__RESTRICT	barrier,
		const void *__RESTRICT	attr,
		unsigned	count )

Initialize a thread barrier.

This function initializes a thread barrier for use among the specified number of threads.

Parameters

barrier	The barrier to initialize.
attr	Reserved for POSIX compatibility. Always pass NULL.
count	The number of threads the barrier will expect.

Returns

0 on success, non-zero error code on failure

Error Conditions:

EINVAL - NULL was passed for barrier
EINVAL - Non-NULL was passed for attr
EINVAL - count == 0 or count > UINT32_MAX

thd_barrier_wait()

int thd_barrier_wait

(

thd_barrier_t *

barrier

)

Wait on a thread barrier.

This function synchronizes the participating threads at the barrier specified. The calling thread will block until the required number of threads (specified by the barrier's count) have called this function to wait on the barrier.

Parameters

barrier

The barrier to wait on.

Returns

0 or THD_BARRIER_SERIAL_THREAD on success, non-zero error code on failure

Error Conditions:

EINVAL - NULL was passed for barrier
EINVAL - barrier was destroyed via thd_barrier_destroy()
EINVAL - A call to thd_barrier_destroy() is in progress for the specified barrier
EPERM - Function was called in an interrupt context