ARGOBOTS  7a09f9f632d87ed4f43aec50889983fa897fba10
Data Structures | Macros | Typedefs | Functions
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.

void thread(void *)
{
if (...) {
ABT_cond_wait(cond, mutex);
} else {
}
}

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]condcondition 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]newcondcondition 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]condcondition 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]condcondition 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]condcondition variable handle
[in]mutexmutex handle
[in]abstimeabsolute 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]condcondition variable handle
[in]mutexmutex handle
Returns
Error code

Definition at line 151 of file cond.c.

ABT_cond_timedwait
int ABT_cond_timedwait(ABT_cond cond, ABT_mutex mutex, const struct timespec *abstime) ABT_API_PUBLIC
Wait on a condition variable with a timeout limit.
Definition: cond.c:227
ABT_mutex
struct ABT_mutex_opaque * ABT_mutex
Mutex handle type.
Definition: abt.h:945
ABT_cond_memory
A struct that can be converted to ABT_cond.
Definition: abt.h:1172
ABT_mutex_lock
int ABT_mutex_lock(ABT_mutex mutex) ABT_API_PUBLIC
Lock a mutex.
Definition: mutex.c:181
ABT_COND_MEMORY_GET_HANDLE
#define ABT_COND_MEMORY_GET_HANDLE(p_cond_memory)
Obtain ABT_cond from ABT_cond_memory.
Definition: abt.h:1220
ABT_MUTEX_MEMORY_GET_HANDLE
#define ABT_MUTEX_MEMORY_GET_HANDLE(p_mutex_memory)
Obtain ABT_mutex from ABT_mutex_memory.
Definition: abt.h:1157
ABT_cond_wait
int ABT_cond_wait(ABT_cond cond, ABT_mutex mutex) ABT_API_PUBLIC
Wait on a condition variable.
Definition: cond.c:151
ABT_mutex_memory
A struct that can be converted to ABT_mutex.
Definition: abt.h:1089
ABT_COND_INITIALIZER
#define ABT_COND_INITIALIZER
Initialize ABT_cond_memory.
Definition: abt.h:1203
ABT_cond
struct ABT_cond_opaque * ABT_cond
Condition variable handle type.
Definition: abt.h:959
ABT_mutex_unlock
int ABT_mutex_unlock(ABT_mutex mutex) ABT_API_PUBLIC
Unlock a mutex.
Definition: mutex.c:357
ABT_MUTEX_INITIALIZER
#define ABT_MUTEX_INITIALIZER
Initialize ABT_mutex_memory.
Definition: abt.h:1114
ABT_cond_signal
int ABT_cond_signal(ABT_cond cond) ABT_API_PUBLIC
Signal a condition.
Definition: cond.c:284