Condition Variable

This group is for Condition Variable. More...

Data Structures
struct	ABT_cond_memory
	A struct that can be converted to ABT_cond. More...

Macros
#define	ABT_COND_INITIALIZER   { { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 } }
	Initialize ABT_cond_memory. More...
#define	ABT_COND_MEMORY_GET_HANDLE(p_cond_memory)   ((ABT_cond)p_cond_memory)
	Obtain ABT_cond from ABT_cond_memory. More...

Typedefs
typedef struct ABT_cond_opaque *	ABT_cond
	Condition variable handle type. More...

Functions
int	ABT_cond_create (ABT_cond *newcond)
	Create a new condition variable. More...
int	ABT_cond_free (ABT_cond *cond)
	Free a condition variable. More...
int	ABT_cond_wait (ABT_cond cond, ABT_mutex mutex)
	Wait on a condition variable. More...
int	ABT_cond_timedwait (ABT_cond cond, ABT_mutex mutex, const struct timespec *abstime)
	Wait on a condition variable with a timeout limit. More...
int	ABT_cond_signal (ABT_cond cond)
	Signal a condition. More...
int	ABT_cond_broadcast (ABT_cond cond)
	Broadcast a condition. More...

Detailed Description

This group is for Condition Variable.

Macro Definition Documentation

ABT_COND_INITIALIZER

#define ABT_COND_INITIALIZER   { { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 } }

Initialize ABT_cond_memory.

ABT_COND_INITIALIZER statically initializes ABT_cond_memory.

The following example shows how to use ABT_COND_INITIALIZER.

ABT_mutex_memory mutex_mem = ABT_MUTEX_INITIALIZER;
ABT_cond_memory cond_mem = ABT_COND_INITIALIZER;
 
void thread(void *)
{
    ABT_mutex mutex = ABT_MUTEX_MEMORY_GET_HANDLE(&mutex_mem);
    ABT_cond cond = ABT_COND_MEMORY_GET_HANDLE(&cond_mem);
    ABT_mutex_lock(mutex);
    if (...) {
       ABT_cond_wait(cond, mutex);
    } else {
       ABT_cond_signal(cond);
    }
    ABT_mutex_unlock(mutex);
}

ABT_cond_memory that is in use may not be initialized again.

Definition at line 1203 of file abt.h.

ABT_COND_MEMORY_GET_HANDLE

#define ABT_COND_MEMORY_GET_HANDLE

(

p_cond_memory

)

((ABT_cond)p_cond_memory)

Obtain ABT_cond from ABT_cond_memory.

ABT_COND_MEMORY_GET_HANDLE() takes the pointer p_cond_memory, which points to ABT_cond_memory, and returns ABT_cond that internally uses p_cond_memory to store the data. If the memory pointed to by p_cond_memory is not properly initialized, it returns a corrupted condition variable.

ABT_cond obtained by ABT_COND_MEMORY_GET_HANDLE() may not be freed by ABT_cond_free(). The lifetime of ABT_cond obtained by ABT_COND_MEMORY_GET_HANDLE() is the same as that of ABT_cond_memory.

Definition at line 1220 of file abt.h.

Typedef Documentation

ABT_cond

typedef struct ABT_cond_opaque* ABT_cond

Condition variable handle type.

A NULL handle of this type is ABT_COND_NULL.

Definition at line 959 of file abt.h.

Function Documentation

ABT_cond_broadcast()

int ABT_cond_broadcast

(

ABT_cond

cond

)

Broadcast a condition.

ABT_cond_broadcast() signals all waiters that are blocked on the condition variable cond. The caller does not need to be holding a mutex associated with cond. This routine has no effect if no waiter is currently blocked on cond.

Execution context

This routine can be called in any execution context. Argobots does not need to 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_COND is returned if cond is ABT_COND_NULL.

Parameters

[in]

cond

condition variable handle

Returns

Error code

Definition at line 316 of file cond.c.

ABT_cond_create()

int ABT_cond_create

(

ABT_cond *

newcond

)

Create a new condition variable.

ABT_cond_create() creates a new condition variable and returns its handle through newcond.

newcond must be freed by ABT_cond_free() after its use.

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

[Argobots 1.x] newcond is set to ABT_COND_NULL if an error occurs.
[Argobots 2.0] newcond 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 newcond 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_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 newcond is NULL, the results are undefined.

Parameters

[out]

newcond

condition variable handle

Returns

Error code

Definition at line 42 of file cond.c.

ABT_cond_free()

int ABT_cond_free

(

ABT_cond *

cond

)

Free a condition variable.

ABT_cond_free() deallocates the resource used for the condition variable cond and sets cond to ABT_COND_NULL.

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

[Argobots 1.x] ABT_ERR_COND is returned if this routine finds a waiter on cond.
[Argobots 2.0] The results of this routine are undefined if a waiter is blocked on cond.

Rationale

The current implementation of this check is crude considering the asynchronous nature of cond. From Argobots 2.0, it becomes the user's responsibility to ensure that no waiter is blocked on cond.

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_COND is returned if cond points to ABT_COND_NULL.
[Argobots 1.x] ABT_ERR_COND is returned if there is a waiter blocked on cond.

Undefined behavior

If Argobots is not initialized, the results are undefined.
If cond is NULL, the results are undefined.
If cond is accessed after calling this routine, the results are undefined.
[Argobots 2.0] If there is a waiter blocked on cond, the results are undefined.

Parameters

[in,out]

cond

condition variable handle

Returns

Error code

Definition at line 89 of file cond.c.

ABT_cond_signal()

int ABT_cond_signal

(

ABT_cond

cond

)

Signal a condition.

ABT_cond_signal() signals another waiter that is blocked on the condition variable cond. Only one waiter is signaled and woken up. The caller does not need to be holding a mutex associated with cond. This routine has no effect if no waiter is currently blocked on cond.

Execution context

This routine can be called in any execution context. Argobots does not need to 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_COND is returned if cond is ABT_COND_NULL.

Parameters

[in]

cond

condition variable handle

Returns

Error code

Definition at line 284 of file cond.c.

ABT_cond_timedwait()

int ABT_cond_timedwait	(	ABT_cond	cond,
		ABT_mutex	mutex,
		const struct timespec *	abstime
	)

Wait on a condition variable with a timeout limit.

The caller of ABT_cond_timedwait() waits on the condition variable cond until either it is signaled or the absolute time specified by abstime passes. The user must call this routine while the mutex mutex is locked. mutex will be automatically released while waiting. When the caller is woken up, mutex will be automatically locked by the caller. The user is then responsible for unlocking mutex. If the system time exceeds abstime before cond is signaled, ABT_ERR_COND_TIMEDOUT is returned.

Note

clock_gettime() can be used to obtain the current system time.

// #include <time.h> is needed.
struct timespec ts;
clock_gettime(CLOCK_REALTIME, &ts);
ts.tv_sec += 10; // timeout = current time + 10 seconds.
ABT_cond_timedwait(cond, mutex, &ts);

This routine associates mutex with cond until this routine returns, so the user may not use more than one mutex for the same cond.

This routine returns with mutex locked even if an error occurs.

If mutex is a recursive mutex, mutex must be locked only once by the caller.

Note

Unlike other implementations of condition variables, a spurious wakeup never occurs.

Execution context

This routine can be called in any execution context. Argobots does not need to be initialized. This routine may switch the context of the calling ULT.

Errors

ABT_SUCCESS is returned if this caller is woken up by a signal.
ABT_ERR_COND_TIMEDOUT is returned if the system time exceeds abstime before cond is signaled.
ABT_ERR_INV_COND is returned if cond is ABT_COND_NULL.
ABT_ERR_INV_MUTEX is returned if mutex is ABT_MUTEX_NULL.

Undefined behavior

If abstime is NULL, the results are undefined.
If mutex is not locked, the results are undefined.
If mutex is a recursive mutex and the caller does not have ownership of mutex, the results are undefined.
If mutex is a recursive mutex and has been locked more than once, the results are undefined.
If cond has been associated with a mutex other than mutex, the results are undefined.

Parameters

[in]	cond	condition variable handle
[in]	mutex	mutex handle
[in]	abstime	absolute time for timeout

Returns

Error code

Definition at line 227 of file cond.c.

ABT_cond_wait()

int ABT_cond_wait	(	ABT_cond	cond,
		ABT_mutex	mutex
	)

Wait on a condition variable.

The caller of ABT_cond_wait() waits on the condition variable cond until it is signaled. The user must call this routine while the mutex mutex is locked. mutex will be automatically released while waiting. When the caller is woken up, mutex will be automatically locked by the caller. The user is then responsible for unlocking mutex.

This routine associates mutex with cond until this routine returns, so the user may not use more than one mutex for the same cond.

This routine returns with mutex locked even if an error occurs.

If mutex is a recursive mutex, mutex must be locked only once by the caller.

Note

Unlike other implementations of condition variables, a spurious wakeup never occurs.

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

[Argobots 1.x] If a tasklet calls this routine, ABT_ERR_COND 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 does not need to be initialized. This routine may switch the context of the calling ULT.
[Argobots 2.0] This routine can be called in any execution context. Argobots does not need to be initialized. This routine may switch the context of the calling ULT.

Errors

ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_COND is returned if cond is ABT_COND_NULL.
ABT_ERR_INV_MUTEX is returned if mutex is ABT_MUTEX_NULL.
[Argobots 1.x] ABT_ERR_COND is returned if the caller is a tasklet.

Undefined behavior

If mutex is not locked, the results are undefined.
If mutex is a recursive mutex and the caller does not have ownership of mutex, the results are undefined.
If mutex is a recursive mutex and has been locked more than once, the results are undefined.
If cond has been associated with a mutex other than mutex, the results are undefined.

Parameters

[in]	cond	condition variable handle
[in]	mutex	mutex handle

Returns

Error code

Definition at line 151 of file cond.c.