Execution-Stream Barrier

This group is for Execution-Stream Barrier. More...

Typedefs
typedef struct ABT_xstream_barrier_opaque *	ABT_xstream_barrier
	Execution-stream barrier handle type. More...

Functions
int	ABT_xstream_barrier_create (uint32_t num_waiters, ABT_xstream_barrier *newbarrier)
	Create a new execution-stream barrier. More...
int	ABT_xstream_barrier_free (ABT_xstream_barrier *barrier)
	Free an execution-stream barrier. More...
int	ABT_xstream_barrier_wait (ABT_xstream_barrier barrier)
	Wait on an execution-stream barrier. More...

Detailed Description

This group is for Execution-Stream Barrier.

Typedef Documentation

ABT_xstream_barrier

typedef struct ABT_xstream_barrier_opaque* ABT_xstream_barrier

Execution-stream barrier handle type.

A NULL handle of this type is ABT_XSTREAM_BARRIER_NULL.

Definition at line 801 of file abt.h.

Function Documentation

ABT_xstream_barrier_create()

int ABT_xstream_barrier_create	(	uint32_t	num_waiters,
		ABT_xstream_barrier *	newbarrier
	)

Create a new execution-stream barrier.

ABT_xstream_barrier_create() creates a new execution-stream barrier and returns its handle through newbarrier. num_waiters specifies the number of waiters that must call ABT_xstream_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_xstream_barrier_free() after its use.

Changes from Argobots 1.x to Argobots 2.0 (planned)

[Argobots 1.x] newbarrier is set to ABT_XSTREAM_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	execution-stream barrier handle

Returns

Error code

Definition at line 44 of file stream_barrier.c.

ABT_xstream_barrier_free()

int ABT_xstream_barrier_free

(

ABT_xstream_barrier *

barrier

)

Free an execution-stream barrier.

ABT_xstream_barrier_free() deallocates the resource used for the execution-stream barrier barrier and sets barrier to ABT_XSTREAM_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_XSTREAM_BARRIER is returned if barrier points to ABT_XSTREAM_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

execution-stream barrier handle

Returns

Error code

Definition at line 101 of file stream_barrier.c.

ABT_xstream_barrier_wait()

int ABT_xstream_barrier_wait

(

ABT_xstream_barrier

barrier

)

Wait on an execution-stream barrier.

The caller of ABT_xstream_barrier_wait() waits on the execution-stream barrier barrier. The caller is blocked until as many waiters as the number of waiters specified by ABT_xstream_barrier_create() reach barrier. If the caller is either a ULT or a tasklet, the underlying execution stream is blocked on barrier.

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_XSTREAM_BARRIER is returned if barrier is ABT_XSTREAM_BARRIER_NULL.

Undefined behavior

If Argobots is not initialized, the results are undefined.

Parameters

[in]

barrier

execution-stream barrier handle

Returns

Error code

Definition at line 140 of file stream_barrier.c.