|
ARGOBOTS
dce6e727ffc4ca5b3ffc04cb9517c6689be51ec5
|
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... | |
This group is for Mutex.
| #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.
ABT_mutex_memory that is in use may not be initialized again.
| #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.
| #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.
ABT_mutex_memory that is in use may not be initialized again.
| typedef struct ABT_mutex_opaque* ABT_mutex |
| 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.
newmutex is set to ABT_MUTEX_NULL if an error occurs.newmutex is not updated if an error occurs. newmutex when an error occurs. 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.newmutex is NULL, the results are undefined.| [out] | newmutex | mutex handle |
| 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.
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.
ABT_ERR_INV_MUTEX_ATTR if attr is ABT_MUTEX_ATTR_NULL.attr is ABT_MUTEX_ATTR_NULL. newmutex is set to ABT_MUTEX_NULL if an error occurs.newmutex is not updated if an error occurs. newmutex when an error occurs. 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.newmutex is NULL, the results are undefined.| [in] | attr | mutex attribute handle |
| [out] | newmutex | mutex handle |
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.
ABT_SUCCESS is returned if this routine succeeds.result is NULL, the results are undefined.| [in] | mutex1 | mutex handle 1 |
| [in] | mutex2 | mutex handle 2 |
| [out] | result | result (ABT_TRUE: same, ABT_FALSE: not same) |
| 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.
mutex regardless of whether it is locked or not.ABT_SUCCESS is returned if this routine succeeds.ABT_ERR_INV_MUTEX is returned if mutex points to ABT_MUTEX_NULL.mutex is NULL, the results are undefined.mutex, the results are undefined.mutex is accessed after calling this routine, the results are undefined.| [in,out] | mutex | mutex handle |
| 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.
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.attr is NULL, the results are undefined.| [in] | mutex | mutex handle |
| [out] | attr | mutex attribute handle |
| 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.
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.ABT_SUCCESS is returned if this routine succeeds.ABT_ERR_INV_MUTEX is returned if mutex is ABT_MUTEX_NULL.| [in] | mutex | mutex handle |
| 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().
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.ABT_SUCCESS is returned if this routine succeeds.ABT_ERR_INV_MUTEX is returned if mutex is ABT_MUTEX_NULL.| [in] | mutex | mutex handle |
| 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().
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.ABT_SUCCESS is returned if this routine succeeds.ABT_ERR_INV_MUTEX is returned if mutex is ABT_MUTEX_NULL.| [in] | mutex | mutex handle |
| 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.
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.ABT_SUCCESS is returned if this routine succeeds.ABT_ERR_INV_MUTEX is returned if mutex is ABT_MUTEX_NULL.| [in] | mutex | mutex handle |
| 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.
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.| [in] | mutex | mutex handle |
| 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.
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.ABT_SUCCESS is returned if this routine succeeds.ABT_ERR_INV_MUTEX is returned if mutex is ABT_MUTEX_NULL.mutex is not locked, the results are undefined.mutex is a recursive mutex and the caller does not have ownership of mutex, the results are undefined.| [in] | mutex | mutex handle |
| 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().
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.ABT_SUCCESS is returned if this routine succeeds.ABT_ERR_INV_MUTEX is returned if mutex is ABT_MUTEX_NULL.mutex is not locked, the results are undefined.mutex is a recursive mutex and the caller does not have ownership of mutex, the results are undefined.| [in] | mutex | mutex handle |
| 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().
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.ABT_SUCCESS is returned if this routine succeeds.ABT_ERR_INV_MUTEX is returned if mutex is ABT_MUTEX_NULL.mutex is not locked, the results are undefined.mutex is a recursive mutex and the caller does not have ownership of mutex, the results are undefined.| [in] | mutex | mutex handle |
1.8.17