Mutex is a synchronization method to support mutual exclusion between ULTs. When more than one ULT competes for locking the same mutex, only one ULT is guaranteed to lock the mutex. Other ULTs are blocked and wait until the ULT which locked the mutex unlocks it. When the mutex is unlocked, another ULT is able to lock the mutex again.
The mutex is basically intended to be used by ULTs but it can also be used by tasklets or external threads. In that case, the mutex will behave like a spinlock.
Create a new mutex.
ABT_mutex_create() creates a new mutex object with default attributes and returns its handle through newmutex. To set different attributes, please use ABT_mutex_create_with_attr(). If an error occurs in this routine, a non-zero error code will be returned and newmutex will be set to ABT_MUTEX_NULL.
- Parameters
-
| [out] | newmutex | handle to a new mutex |
- Returns
- Error code
- Return values
-
Definition at line 35 of file mutex.c.
Create a new mutex with attributes.
ABT_mutex_create_with_attr() creates a new mutex object having attributes passed by attr and returns its handle through newmutex. Note that ABT_mutex_create() can be used to create a mutex with default attributes.
If an error occurs in this routine, a non-zero error code will be returned and newmutex will be set to ABT_MUTEX_NULL.
- Parameters
-
| [in] | attr | handle to the mutex attribute object |
| [out] | newmutex | handle to a new mutex |
- Returns
- Error code
- Return values
-
Definition at line 65 of file mutex.c.
Compare two mutex handles for equality.
ABT_mutex_equal() compares two mutex handles for equality. If two handles are associated with the same mutex object, result will be set to ABT_TRUE. Otherwise, result will be set to ABT_FALSE.
- Parameters
-
| [in] | mutex1 | handle to the mutex 1 |
| [in] | mutex2 | handle to the mutex 2 |
| [out] | result | comparison result (ABT_TRUE: same, ABT_FALSE: not same) |
- Returns
- Error code
- Return values
-
Definition at line 666 of file mutex.c.
Free the mutex object.
ABT_mutex_free() deallocates the memory used for the mutex object associated with the handle mutex. If it is successfully processed, mutex is set to ABT_MUTEX_NULL.
Using the mutex handle after calling ABT_mutex_free() may cause undefined behavior.
- Parameters
-
| [in,out] | mutex | handle to the mutex |
- Returns
- Error code
- Return values
-
Definition at line 102 of file mutex.c.
Lock the mutex.
ABT_mutex_lock() locks the mutex mutex. If this routine successfully returns, the caller work unit acquires the mutex. If the mutex has already been locked, the caller will be blocked until the mutex becomes available. When the caller is a ULT and is blocked, the context is switched to the scheduler of the associated ES to make progress of other work units.
The mutex can be used by any work units, but tasklets are discouraged to use the mutex because any blocking calls like ABT_mutex_lock() may block the associated ES and prevent other work units from being scheduled on the ES.
- Parameters
-
| [in] | mutex | handle to the mutex |
- Returns
- Error code
- Return values
-
Definition at line 141 of file mutex.c.
Referenced by ABT_mutex_lock_high().
Lock the mutex without context switch.
ABT_mutex_spinlock() locks the mutex without context switch. If this routine successfully returns, the caller work unit acquires the mutex. If the mutex has already been locked, the caller will be blocked until the mutex becomes available. Unlike ABT_mutex_lock(), the ULT calling this routine continuously tries to lock the mutex without context switch.
- Parameters
-
| [in] | mutex | handle to the mutex |
- Returns
- Error code
- Return values
-
Definition at line 386 of file mutex.c.
Attempt to lock a mutex without blocking.
ABT_mutex_trylock() attempts to lock the mutex mutex without blocking the caller work unit. If this routine successfully returns, the caller acquires the mutex.
If the mutex has already been locked and there happens no error, ABT_ERR_MUTEX_LOCKED will be returned immediately without blocking the caller.
- Parameters
-
| [in] | mutex | handle to the mutex |
- Returns
- Error code
- Return values
-
| ABT_SUCCESS | on success |
| ABT_ERR_MUTEX_LOCKED | when mutex has already been locked |
Definition at line 334 of file mutex.c.
Unlock the mutex.
ABT_mutex_unlock() unlocks the mutex mutex. If the caller locked the mutex, this routine unlocks the mutex. However, if the caller did not lock the mutex, this routine may result in undefined behavior.
- Parameters
-
| [in] | mutex | handle to the mutex |
- Returns
- Error code
- Return values
-
Definition at line 433 of file mutex.c.
Hand over the mutex within the ES.
ABT_mutex_unlock_se() first tries to hand over the mutex to a ULT, which is waiting for this mutex and is running on the same ES as the caller. If no ULT on the same ES is waiting, it unlocks the mutex like ABT_mutex_unlock().
If the caller ULT locked the mutex, this routine unlocks the mutex. However, if the caller ULT did not lock the mutex, this routine may result in undefined behavior.
- Parameters
-
| [in] | mutex | handle to the mutex |
- Returns
- Error code
- Return values
-
Definition at line 598 of file mutex.c.
1.8.11
