pthread_barrier_init()

Updated: April 19, 2023

Initialize a barrier object

Synopsis:

#include <pthread.h>

int pthread_barrier_init( 
                    pthread_barrier_t * barrier,
                    const pthread_barrierattr_t * attr
                    unsigned int count );

Arguments:

barrier
A pointer to the pthread_barrier_t object that you want to initialize.
attr
NULL, or a pointer to a pthread_barrierattr_t structure that specifies the attributes that you want to use for the barrier.
count
The number of threads that must call pthread_barrier_wait() before any of them successfully returns from the call. This value must be greater than zero.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The pthread_barrier_init() function allocates any resources required to use the barrier referenced by barrier and initializes the barrier with attributes referenced by attr. If attr is NULL, the default barrier attributes are used. The effect is the same as passing the address of a default barrier attributes object. Once it's initialized, you can use the barrier any number of times without reinitializing it.

CAUTION:
You should allocate synchronization objects only in normal memory mappings. On certain processors, the atomic operations performed on synchronization objects will cause a fault if the control structure is allocated in uncached memory.

If pthread_barrier_init() fails, the barrier isn't initialized.

In cases where the default barrier attributes are appropriate, you can use PTHREAD_BARRIER_INITIALIZER() macro to initialize barriers that are statically allocated. The effect is equivalent to dynamic initialization by a call to pthread_barrier_init() with parameter attr specified as NULL, except that no error checks are performed.

Returns:

EAGAIN
The system lacks the necessary resources to initialize another barrier.
EFAULT
A fault occurred when the kernel tried to access barrier or attr.
EINVAL
Invalid value specified by attr.
EOK
Success.

Classification:

POSIX 1003.1

Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes