ARGOBOTS  be805649b56a69fc4df1b6bc4efbc8911b854459
Typedefs | Functions
Barrier

This group is for Barrier. More...

Typedefs

typedef struct ABT_barrier_opaque * ABT_barrier
 Barrier handle type. More...
 

Functions

int ABT_barrier_create (uint32_t num_waiters, ABT_barrier *newbarrier)
 Create a new barrier. More...
 
int ABT_barrier_reinit (ABT_barrier barrier, uint32_t num_waiters)
 Reinitialize a barrier with a new number of waiters. More...
 
int ABT_barrier_free (ABT_barrier *barrier)
 Free a barrier. More...
 
int ABT_barrier_wait (ABT_barrier barrier)
 Wait on a barrier. More...
 
int ABT_barrier_get_num_waiters (ABT_barrier barrier, uint32_t *num_waiters)
 Get the number of waiters of a barrier. More...
 

Detailed Description

This group is for Barrier.

Typedef Documentation

◆ ABT_barrier

typedef struct ABT_barrier_opaque* ABT_barrier

Barrier handle type.

A NULL handle of this type is ABT_BARRIER_NULL.

Definition at line 1005 of file abt.h.

Function Documentation

◆ ABT_barrier_create()

int ABT_barrier_create ( uint32_t  num_waiters,
ABT_barrier newbarrier 
)

Create a new barrier.

ABT_barrier_create() creates a new barrier and returns its handle through newbarrier. num_waiters specifies the number of waiters that must call ABT_barrier_wait() before any of the waiters successfully return from the call. num_waiters must be greater than zero.

newbarrier must be freed by ABT_barrier_free() after its use.

Changes from Argobots 1.0 to Argobots 1.1
[Argobots 1.0] This routine accepts zero as num_waiters.
[Argobots 1.1] This routine returns ABT_ERR_INV_ARG if num_waiters is zero.
Rationale
A barrier whose num_waiters is 0 cannot define a wait operation and should be prohibited. Note that even Argobots 1.0 does not allow ABT_barrier_wait() with a barrier whose num_waiters is 0.
Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] newbarrier is set to ABT_BARRIER_NULL if an error occurs.
[Argobots 2.0] newbarrier is not updated if an error occurs.
Rationale
To ensure the atomicity of the API, Argobots 2.0 guarantees that the routine has no effect when an error is returned unless otherwise noted. Argobots 2.0 does not update newbarrier when an error occurs.
Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_ARG is returned if num_waiters is zero.
ABT_ERR_MEM is returned if memory allocation fails.
ABT_ERR_SYS is returned if an error related to system calls and standard libraries occurs.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If newbarrier is NULL, the results are undefined.
Parameters
[in]num_waitersnumber of waiters
[out]newbarrierbarrier handle
Returns
Error code

Definition at line 47 of file barrier.c.

◆ ABT_barrier_free()

int ABT_barrier_free ( ABT_barrier barrier)

Free a barrier.

ABT_barrier_free() deallocates the resource used for the barrier barrier and sets barrier to ABT_BARRIER_NULL.

Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_BARRIER is returned if barrier points to ABT_BARRIER_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If barrier is NULL, the results are undefined.
If there is a waiter blocked on barrier, the results are undefined.
If barrier is accessed after calling this routine, the results are undefined.
Parameters
[in,out]barrierbarrier handle
Returns
Error code

Definition at line 144 of file barrier.c.

◆ ABT_barrier_get_num_waiters()

int ABT_barrier_get_num_waiters ( ABT_barrier  barrier,
uint32_t *  num_waiters 
)

Get the number of waiters of a barrier.

ABT_barrier_get_num_waiters() returns the number of waiters of the barrier barrier through num_waiters. The number of waiters is set by ABT_barrier_create() and can be updated by ABT_barrier_reinit().

Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_BARRIER is returned if barrier is ABT_BARRIER_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If num_waiters is NULL, the results are undefined.
Parameters
[in]barrierhandle to the barrier
[out]num_waitersnumber of waiters
Returns
Error code

Definition at line 258 of file barrier.c.

◆ ABT_barrier_reinit()

int ABT_barrier_reinit ( ABT_barrier  barrier,
uint32_t  num_waiters 
)

Reinitialize a barrier with a new number of waiters.

ABT_barrier_reinit() reinitializes the barrier barrier with the new number of waiters num_waiters. num_waiters must be greater than zero.

Changes from Argobots 1.0 to Argobots 1.1
[Argobots 1.0] This routine accepts zero as num_waiters.
[Argobots 1.1] This routine returns ABT_ERR_INV_ARG if num_waiters is zero.
Rationale
A barrier whose num_waiters is 0 cannot define a wait operation and should be prohibited. Note that even Argobots 1.0 does not allow ABT_barrier_wait() with a barrier whose num_waiters is 0.
Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_ARG is returned if num_waiters is zero.
ABT_ERR_INV_BARRIER is returned if barrier is ABT_BARRIER_NULL.
ABT_ERR_MEM is returned if memory allocation fails.
ABT_ERR_SYS is returned if an error related to system calls and standard libraries occurs.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If there is a waiter blocked on barrier, the results are undefined.
If barrier is accessed concurrently, the results are undefined.
Parameters
[in]barrierbarrier handle
[in]num_waitersnumber of waiters
Returns
Error code

Definition at line 102 of file barrier.c.

◆ ABT_barrier_wait()

int ABT_barrier_wait ( ABT_barrier  barrier)

Wait on a barrier.

The caller of ABT_barrier_wait() waits on the barrier barrier. The caller suspends until as many waiters as the number of waiters specified by ABT_barrier_create() or ABT_barrier_reinit() reach barrier.

Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] If a tasklet calls this routine, ABT_ERR_BARRIER is returned.
[Argobots 2.0] A tasklet may call this routine.
Rationale
Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general.
Execution context
[Argobots 1.x] This routine can be called in a ULT context or an external thread context. Argobots must be initialized. This routine may switch the context of the calling ULT if the caller is not the last waiter that waits on barrier. Otherwise, this routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
[Argobots 2.0] This routine can be called in any execution context. Argobots must be initialized. This routine may switch the context of the calling ULT if the caller is not the last waiter that waits on barrier. Otherwise, this routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_BARRIER is returned if barrier is ABT_BARRIER_NULL.
[Argobots 1.x] ABT_ERR_BARRIER is returned if the caller is a tasklet.
Undefined behavior
If Argobots is not initialized, the results are undefined.
Parameters
[in]barrierbarrier handle
Returns
Error code

Definition at line 197 of file barrier.c.