ARGOBOTS  29b0d4cc91ca184a8278ddf690fd0bcb2119000e
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Functions
Mutex

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 attributes. More...
 
int ABT_mutex_free (ABT_mutex *mutex)
 Free the mutex object. More...
 
int ABT_mutex_lock (ABT_mutex mutex)
 Lock the mutex. More...
 
int ABT_mutex_lock_low (ABT_mutex mutex)
 Lock the mutex with low priority. More...
 
int ABT_mutex_trylock (ABT_mutex mutex)
 Attempt to lock a mutex without blocking. More...
 
int ABT_mutex_spinlock (ABT_mutex mutex)
 Lock the mutex without context switch. More...
 
int ABT_mutex_unlock (ABT_mutex mutex)
 Unlock the mutex. More...
 
int ABT_mutex_unlock_se (ABT_mutex mutex)
 Hand over the mutex within the ES. More...
 
int ABT_mutex_equal (ABT_mutex mutex1, ABT_mutex mutex2, ABT_bool *result)
 Compare two mutex handles for equality. More...
 

Detailed Description

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.

Function Documentation

int ABT_mutex_create ( ABT_mutex newmutex)

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]newmutexhandle to a new mutex
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 38 of file mutex.c.

int ABT_mutex_create_with_attr ( ABT_mutex_attr  attr,
ABT_mutex newmutex 
)

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]attrhandle to the mutex attribute object
[out]newmutexhandle to a new mutex
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 72 of file mutex.c.

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 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]mutex1handle to the mutex 1
[in]mutex2handle to the mutex 2
[out]resultcomparison result (ABT_TRUE: same, ABT_FALSE: not same)
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 418 of file mutex.c.

int ABT_mutex_free ( ABT_mutex mutex)

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]mutexhandle to the mutex
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 108 of file mutex.c.

int ABT_mutex_lock ( ABT_mutex  mutex)

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]mutexhandle to the mutex
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 140 of file mutex.c.

Referenced by ABT_mutex_lock_high().

int ABT_mutex_lock_low ( ABT_mutex  mutex)

Lock the mutex with low priority.

ABT_mutex_lock_low() locks the mutex with low priority, while ABT_mutex_lock() does with high priority. Apart from the priority, other semantics of ABT_mutex_lock_low() are the same as those of ABT_mutex_lock().

Parameters
[in]mutexhandle to the mutex
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 181 of file mutex.c.

int ABT_mutex_spinlock ( ABT_mutex  mutex)

Lock the mutex without context switch.

ABT_mutex_spinlock() locks the mutex without context switch. If this routine successfully returns, the caller thread 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]mutexhandle to the mutex
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 278 of file mutex.c.

int ABT_mutex_trylock ( ABT_mutex  mutex)

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]mutexhandle to the mutex
Returns
Error code
Return values
ABT_SUCCESSon success
ABT_ERR_MUTEX_LOCKEDwhen mutex has already been locked

Definition at line 231 of file mutex.c.

int ABT_mutex_unlock ( ABT_mutex  mutex)

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]mutexhandle to the mutex
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 318 of file mutex.c.

int ABT_mutex_unlock_se ( ABT_mutex  mutex)

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]mutexhandle to the mutex
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 364 of file mutex.c.