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 1029 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_waiters	number of waiters
[out]	newbarrier	barrier 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] barrier barrier 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]	barrier	handle to the barrier
[out]	num_waiters	number 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]	barrier	barrier handle
[in]	num_waiters	number 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] barrier barrier handle

Returns: Error code

Definition at line 197 of file barrier.c.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ ABT_barrier

Function Documentation

◆ ABT_barrier_create()

◆ ABT_barrier_free()

◆ ABT_barrier_get_num_waiters()

◆ ABT_barrier_reinit()

◆ ABT_barrier_wait()