ARGOBOTS  1.1
Data Structures | Macros | Typedefs | Functions
Mutex

This group is for Mutex. More...

Data Structures

struct  ABT_mutex_memory
 A struct that can be converted to ABT_mutex. More...
 

Macros

#define ABT_MUTEX_INITIALIZER   { { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 } }
 Initialize ABT_mutex_memory. More...
 
#define ABT_RECURSIVE_MUTEX_INITIALIZER   { { 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 } }
 Initialize ABT_mutex_memory with a recursive property. More...
 
#define ABT_MUTEX_MEMORY_GET_HANDLE(p_mutex_memory)   ((ABT_mutex)p_mutex_memory)
 Obtain ABT_mutex from ABT_mutex_memory. More...
 

Typedefs

typedef struct ABT_mutex_opaque * ABT_mutex
 Mutex handle type. More...
 

Functions

int ABT_mutex_create (ABT_mutex *newmutex)
 Create a new mutex. More...
 
int ABT_mutex_create_with_attr (ABT_mutex_attr attr, ABT_mutex *newmutex)
 Create a new mutex with mutex attributes. More...
 
int ABT_mutex_free (ABT_mutex *mutex)
 Free a mutex. More...
 
int ABT_mutex_lock (ABT_mutex mutex)
 Lock a mutex. More...
 
int ABT_mutex_lock_low (ABT_mutex mutex)
 Lock a mutex with low priority. More...
 
int ABT_mutex_lock_high (ABT_mutex mutex)
 Lock a mutex with high priority. More...
 
int ABT_mutex_trylock (ABT_mutex mutex)
 Attempt to lock a mutex. More...
 
int ABT_mutex_spinlock (ABT_mutex mutex)
 Lock a mutex in a busy-wait form. More...
 
int ABT_mutex_unlock (ABT_mutex mutex)
 Unlock a mutex. More...
 
int ABT_mutex_unlock_se (ABT_mutex mutex)
 Unlock a mutex and try to hand it over a waiter associated with the same execution stream. More...
 
int ABT_mutex_unlock_de (ABT_mutex mutex)
 Unlock a mutex and try to hand it over a waiter associated with an execution stream that is different from that of the caller. More...
 
int ABT_mutex_equal (ABT_mutex mutex1, ABT_mutex mutex2, ABT_bool *result)
 Compare two mutex handles for equality. More...
 
int ABT_mutex_get_attr (ABT_mutex mutex, ABT_mutex_attr *attr)
 Get attributes of a mutex. More...
 

Detailed Description

This group is for Mutex.

Macro Definition Documentation

◆ ABT_MUTEX_INITIALIZER

#define ABT_MUTEX_INITIALIZER   { { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 } }

Initialize ABT_mutex_memory.

ABT_MUTEX_INITIALIZER statically initializes ABT_mutex_memory. The created mutex is not recursive.

The following shows how to use ABT_MUTEX_INITIALIZER.

void thread(void *)
{
}

ABT_mutex_memory that is in use may not be initialized again.

Definition at line 1114 of file abt.h.

◆ ABT_MUTEX_MEMORY_GET_HANDLE

#define ABT_MUTEX_MEMORY_GET_HANDLE (   p_mutex_memory)    ((ABT_mutex)p_mutex_memory)

Obtain ABT_mutex from ABT_mutex_memory.

ABT_MUTEX_MEMORY_GET_HANDLE() takes the pointer p_mutex_memory, which points to ABT_mutex_memory, and returns ABT_mutex that internally uses p_mutex_memory to store the data. If the memory pointed to by p_mutex_memory is not properly initialized, it returns a corrupted mutex.

ABT_mutex obtained by ABT_MUTEX_MEMORY_GET_HANDLE() may not be freed by ABT_mutex_free(). The lifetime of ABT_mutex obtained by ABT_MUTEX_MEMORY_GET_HANDLE() is the same as that of ABT_mutex_memory.

Definition at line 1157 of file abt.h.

◆ ABT_RECURSIVE_MUTEX_INITIALIZER

#define ABT_RECURSIVE_MUTEX_INITIALIZER   { { 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 } }

Initialize ABT_mutex_memory with a recursive property.

ABT_RECURSIVE_MUTEX_INITIALIZER statically initializes ABT_mutex_memory. The created mutex is recursive.

The following shows how to use ABT_RECURSIVE_MUTEX_INITIALIZER.

void thread(void *)
{
ABT_mutex rec_mutex = ABT_MUTEX_MEMORY_GET_HANDLE(&rec_mutex_mem);
// rec_mutex is recursive.
ABT_mutex_lock(rec_mutex);
ABT_mutex_lock(rec_mutex);
ABT_mutex_unlock(rec_mutex);
ABT_mutex_unlock(rec_mutex);
}

ABT_mutex_memory that is in use may not be initialized again.

Definition at line 1141 of file abt.h.

Typedef Documentation

◆ ABT_mutex

typedef struct ABT_mutex_opaque* ABT_mutex

Mutex handle type.

A NULL handle of this type is ABT_MUTEX_NULL.

Definition at line 945 of file abt.h.

Function Documentation

◆ ABT_mutex_create()

int ABT_mutex_create ( ABT_mutex newmutex)

Create a new mutex.

ABT_mutex_create() creates a new mutex with default attributes and returns its handle through newmutex.

newmutex must be freed by ABT_mutex_free() after its use.

Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] newmutex is set to ABT_MUTEX_NULL if an error occurs.
[Argobots 2.0] newmutex 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 newmutex 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 newmutex is NULL, the results are undefined.
Parameters
[out]newmutexmutex handle
Returns
Error code

Definition at line 39 of file mutex.c.

◆ ABT_mutex_create_with_attr()

int ABT_mutex_create_with_attr ( ABT_mutex_attr  attr,
ABT_mutex newmutex 
)

Create a new mutex with mutex attributes.

ABT_mutex_create_with_attr() creates a new mutex configured with the mutex attribute attr and returns its handle through newmutex. If attr is ABT_MUTEX_ATTR_NULL, newmutex has default attributes.

Note
To check the details of the default mutex attributes, please see ABT_mutex_attr_create().

This routine does not take the ownership of attr, so it is the user's responsibility to free attr after its use.

newmutex must be freed by ABT_mutex_free() after its use.

Changes from Argobots 1.0 to Argobots 1.1
[Argobots 1.0] This routine returns ABT_ERR_INV_MUTEX_ATTR if attr is ABT_MUTEX_ATTR_NULL.
[Argobots 1.1] This routine uses the default mutex attributes if attr is ABT_MUTEX_ATTR_NULL.
Rationale
Most of the Argobots routines use the default attributes when a NULL handle is passed as a configuration or an attribute. This routine should follow this behavior.
Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] newmutex is set to ABT_MUTEX_NULL if an error occurs.
[Argobots 2.0] newmutex 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 newmutex 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 newmutex is NULL, the results are undefined.
Parameters
[in]attrmutex attribute handle
[out]newmutexmutex handle
Returns
Error code

Definition at line 98 of file mutex.c.

◆ ABT_mutex_equal()

int ABT_mutex_equal ( ABT_mutex  mutex1,
ABT_mutex  mutex2,
ABT_bool result 
)

Compare two mutex handles for equality.

ABT_mutex_equal() compares two mutex handles mutex1 and mutex2 for equality and returns the result through result.

This routine is deprecated since its behavior is the same as comparing values of mutex1 and mutex2.

*result = (mutex1 == mutex2) ? ABT_TRUE : ABT_FALSE;
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.
Undefined behavior
If result is NULL, the results are undefined.
Parameters
[in]mutex1mutex handle 1
[in]mutex2mutex handle 2
[out]resultresult (ABT_TRUE: same, ABT_FALSE: not same)
Returns
Error code

Definition at line 481 of file mutex.c.

◆ ABT_mutex_free()

int ABT_mutex_free ( ABT_mutex mutex)

Free a mutex.

ABT_mutex_free() deallocates the resource used for the mutex mutex and sets mutex to ABT_MUTEX_NULL.

Note
This routine frees mutex regardless of whether it is locked or not.
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_MUTEX is returned if mutex points to ABT_MUTEX_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If mutex is NULL, the results are undefined.
If there is a waiter blocked on mutex, the results are undefined.
If mutex is accessed after calling this routine, the results are undefined.
Parameters
[in,out]mutexmutex handle
Returns
Error code

Definition at line 145 of file mutex.c.

◆ ABT_mutex_get_attr()

int ABT_mutex_get_attr ( ABT_mutex  mutex,
ABT_mutex_attr attr 
)

Get attributes of a mutex.

ABT_mutex_get_attr() returns a newly created attribute object that is copied from the attributes of the mutex mutex through attr. Since this routine allocates a mutex attribute object, it is the user's responsibility to free attr after its use.

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_MUTEX is returned if mutex is ABT_MUTEX_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 attr is NULL, the results are undefined.
Parameters
[in]mutexmutex handle
[out]attrmutex attribute handle
Returns
Error code

Definition at line 514 of file mutex.c.

◆ ABT_mutex_lock()

int ABT_mutex_lock ( ABT_mutex  mutex)

Lock a mutex.

ABT_mutex_lock() locks the mutex mutex. If this routine successfully returns, the caller acquires mutex. If mutex has already been locked, the caller is blocked on mutex until mutex becomes available.

If mutex is recursive, the same caller can acquire multiple levels of ownership over mutex. mutex remains locked until mutex is unlocked as many times as the level of ownership.

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 if mutex is locked and therefore the caller fails to take a lock. 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_MUTEX is returned if mutex is ABT_MUTEX_NULL.
Parameters
[in]mutexmutex handle
Returns
Error code

Definition at line 181 of file mutex.c.

◆ ABT_mutex_lock_high()

int ABT_mutex_lock_high ( ABT_mutex  mutex)

Lock a mutex with high priority.

ABT_mutex_lock_high() locks the mutex mutex with high priority while ABT_mutex_lock() and ABT_mutex_lock_low() do with lower priority. That is, waiters that call the high-priority mutex lock functions might be prioritized over the same mutex. Except for priority, the semantics of ABT_mutex_lock_high() is the same as that of ABT_mutex_lock().

Note
A program that relies on the scheduling order regarding mutex priorities is non-conforming.
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 if mutex is locked and therefore the caller fails to take a lock. 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_MUTEX is returned if mutex is ABT_MUTEX_NULL.
Parameters
[in]mutexmutex handle
Returns
Error code

Definition at line 249 of file mutex.c.

◆ ABT_mutex_lock_low()

int ABT_mutex_lock_low ( ABT_mutex  mutex)

Lock a mutex with low priority.

ABT_mutex_lock_low() locks the mutex mutex with low priority while ABT_mutex_lock() and ABT_mutex_lock_high() do with higher priority. That is, waiters that call the high-priority mutex lock functions might be prioritized over the same mutex. Except for priority, the semantics of ABT_mutex_lock_low() is the same as that of ABT_mutex_lock().

Note
A program that relies on the scheduling order regarding mutex priorities is non-conforming.
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 if mutex is locked and therefore the caller fails to take a lock. 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_MUTEX is returned if mutex is ABT_MUTEX_NULL.
Parameters
[in]mutexmutex handle
Returns
Error code

Definition at line 215 of file mutex.c.

◆ ABT_mutex_spinlock()

int ABT_mutex_spinlock ( ABT_mutex  mutex)

Lock a mutex in a busy-wait form.

ABT_mutex_spinlock() locks the mutex mutex in a busy-wait form. If this routine successfully returns, the caller acquires mutex. If mutex has already been locked, the caller is blocked on mutex until mutex becomes available.

If mutex is recursive, the same caller can acquire multiple levels of ownership over mutex. mutex remain locked until mutex is unlocked as many times as the level of ownership.

Note
ABT_mutex_spinlock() might show a slightly better performance than ABT_mutex_lock() if mutex is uncontended. This routine, however, blocks the underlying execution stream when mutex has already been locked even if the caller is a ULT. This busy-wait behavior is deadlock-prone, so the user should carefully use this routine.
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_MUTEX is returned if mutex is ABT_MUTEX_NULL.
Parameters
[in]mutexmutex handle
Returns
Error code

Definition at line 324 of file mutex.c.

◆ ABT_mutex_trylock()

int ABT_mutex_trylock ( ABT_mutex  mutex)

Attempt to lock a mutex.

ABT_mutex_trylock() attempts to lock the mutex mutex. If this routine returns ABT_SUCCESS, the caller acquires the mutex. If the caller fails to take a lock, ABT_ERR_MUTEX_LOCKED is returned.

If mutex is recursive, the same caller can acquire multiple levels of ownership over mutex. mutex remains locked until mutex is unlocked as many times as the level of ownership.

This trylock operation is atomically strong, so lock acquisition by this routine never fails if mutex is not locked.

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 successfully obtains mutex.
ABT_ERR_MUTEX_LOCKED is returned if this routine fails to obtain mutex.
ABT_ERR_INV_MUTEX is returned if mutex is ABT_MUTEX_NULL.
Parameters
[in]mutexmutex handle
Returns
Error code

Definition at line 284 of file mutex.c.

◆ ABT_mutex_unlock()

int ABT_mutex_unlock ( ABT_mutex  mutex)

Unlock a mutex.

ABT_mutex_unlock() unlocks the mutex mutex.

If mutex is recursive and has been locked more than once, the caller must be the same as that of the corresponding locking function.

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 if a waiter is waiting on mutex. 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_MUTEX is returned if mutex is ABT_MUTEX_NULL.
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.
Parameters
[in]mutexmutex handle
Returns
Error code

Definition at line 357 of file mutex.c.

◆ ABT_mutex_unlock_de()

int ABT_mutex_unlock_de ( ABT_mutex  mutex)

Unlock a mutex and try to hand it over a waiter associated with an execution stream that is different from that of the caller.

ABT_mutex_unlock_de() unlocks the mutex mutex.

If mutex is recursive and has been locked more than once, the caller must be the same as that of the corresponding locking function.

After unlocking the mutex, this routine tries to hand over the ownership of mutex to a waiter that is associated with an execution stream that is different from an execution stream running the caller if the caller is a work unit. If this attempt fails, the behavior of this routine is the same as that of ABT_mutex_unlock().

Note
A program that relies on the handover mechanism provided by this routine is non-conforming.
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 if a waiter is waiting on mutex. 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_MUTEX is returned if mutex is ABT_MUTEX_NULL.
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.
Parameters
[in]mutexmutex handle
Returns
Error code

Definition at line 445 of file mutex.c.

◆ ABT_mutex_unlock_se()

int ABT_mutex_unlock_se ( ABT_mutex  mutex)

Unlock a mutex and try to hand it over a waiter associated with the same execution stream.

ABT_mutex_unlock_se() unlocks the mutex mutex.

If mutex is recursive and has been locked more than once, the caller must be the same as that of the corresponding locking function.

After unlocking the mutex, this routine tries to hand over the ownership of mutex to a waiter that is associated with the same execution stream as an execution stream running the caller if the caller is a work unit. If this attempt fails, the behavior of this routine is the same as that of ABT_mutex_unlock().

Note
A program that relies on the handover mechanism provided by this routine is non-conforming.
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 if a waiter is waiting on mutex. 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_MUTEX is returned if mutex is ABT_MUTEX_NULL.
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.
Parameters
[in]mutexmutex handle
Returns
Error code

Definition at line 401 of file mutex.c.

ABT_mutex
struct ABT_mutex_opaque * ABT_mutex
Mutex handle type.
Definition: abt.h:945
ABT_mutex_lock
int ABT_mutex_lock(ABT_mutex mutex) ABT_API_PUBLIC
Lock a mutex.
Definition: mutex.c:181
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_TRUE
#define ABT_TRUE
True constant for ABT_bool.
Definition: abt.h:748
ABT_FALSE
#define ABT_FALSE
False constant for ABT_bool.
Definition: abt.h:750
ABT_mutex_memory
A struct that can be converted to ABT_mutex.
Definition: abt.h:1089
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_RECURSIVE_MUTEX_INITIALIZER
#define ABT_RECURSIVE_MUTEX_INITIALIZER
Initialize ABT_mutex_memory with a recursive property.
Definition: abt.h:1141