The Globus runtime includes three portable, related mutual exclusion primitives that can be used in applications and libraries. These are
Recursive mutex attribute.
Initialize a mutex.
The globus_mutex_init() function creates a mutex variable that can be used for synchronization. Currently, the attr parameter is ignored.
- Parameters
-
mutex | Pointer to the mutex to initialize. |
attr | Ignored. |
- Returns
- On success, globus_mutex_init() initializes the mutex and returns GLOBUS_SUCCESS. Otherwise, a non-0 value is returned.
Destroy a mutex.
The globus_mutex_destroy() function destroys the mutex pointed to by its
@a mutex parameter. After a mutex is destroyed it may no longer be used
unless it is again initialized by globus_mutex_init(). Behavior is
undefined if globus_mutex_destroy() is called with a pointer to a locked
mutex.
- Parameters
-
mutex | The mutex to destroy |
- Returns
- On success, globus_mutex_destroy() returns GLOBUS_SUCCESS. Otherwise, a non-zero implementation-specific error value is returned.
Lock a mutex.
The globus_mutex_lock() function locks the mutex pointed to by its
@a mutex parameter.
Upon successful
return, the thread calling globus_mutex_lock() has an exclusive
lock on the resources protected by @a mutex. Other threads calling
globus_mutex_lock() will wait until that thread later calls
globus_mutex_unlock() or globus_cond_wait() with that mutex. Depending
on the thread model, calling globus_mutex_lock on a mutex locked
by the current thread will either return an error or result in deadlock.
- Parameters
-
- Returns
- On success, globus_mutex_lock() returns GLOBUS_SUCCESS. Otherwise, a non-zero implementation-specific error value is returned.
Unlock a mutex.
The globus_mutex_unlock() function unlocks the mutex pointed to by its
@a mutex parameter. Upon successful
return, the thread calling globus_mutex_unlock() no longer has an
exclusive lock on the resources protected by @a mutex. Another thread
calling globus_mutex_lock() may be unblocked so that it may acquire
the mutex. Behavior is undefined if globus_mutex_unlock is called with
an unlocked mutex.
- Parameters
-
mutex | The mutex to unlock. |
- Returns
- On success, globus_mutex_unlock() returns GLOBUS_SUCCESS. Otherwise, a non-zero implementation-specific error value is returned.
Lock a mutex if it is not locked.
The globus_mutex_trylock() function locks the mutex pointed to by its
@a mutex parameter if no thread has already locked the mutex. If
@a mutex is locked, then globus_mutex_trylock() returns EBUSY and does
not block the current thread or lock the mutex. Upon successful
return, the thread calling globus_mutex_trylock() has an exclusive
lock on the resources protected by @a mutex. Other threads calling
globus_mutex_lock() will wait until that thread later calls
globus_mutex_unlock() or globus_cond_wait() with that mutex.
- Parameters
-
- Returns
- On success, globus_mutex_trylock() returns GLOBUS_SUCCESS and locks the mutex. If another thread holds the lock, globus_mutex_trylock() returns EBUSY. Otherwise, a non-zero implementation-specific error value is returned.
Initialize a mutex attribute.
The globus_mutexattr_init() function initializes the mutex attribute
structure pointed to by its @a attr parameter. Currently there are
no attribute values that can be set via this API, so there's no real
use to calling this function.
- Parameters
-
attr | Attribute structure to initialize. |
- Returns
- Upon success, globus_mutexattr_init() returns GLOBUS_SUCCESS and modifies the attribute pointed to by attr. If an error occurs, globus_mutexattr_init() returns an implementation-specific non-zero error code.
Destroy a mutex attribute.
The globus_mutexattr_destroy() function destroys the mutex attribute
structure pointed to by its @a attr parameter.
- Parameters
-
attr | Attribute structure to destroy. |
- Returns
- Upon success, globus_mutexattr_destroy() returns GLOBUS_SUCCESS and modifies the attribute pointed to by attr. If an error occurs, globus_mutexattr_destroy() returns an implementation-specific non-zero error code.
Initialize a recursive mutex.
The globus_rmutex_init() function initializes a recursive mutex,
that is, one which may be locked multiple times by a single thread
without causing deadlock.
- Parameters
-
rmutex | A pointer to the mutex to initialize |
rattr | IGNORED |
- Returns
- On success, globus_rmutex_init() initializes the mutex and returns GLOBUS_SUCCESS; otherwise, it returns a non-zero error code.
References globus_cond_init(), globus_mutex_destroy(), and globus_mutex_init().
Lock a recursive mutex.
The globus_rmutex_lock() function acquires the lock controlled by
@a rmutex. This may be called multiple times in a single thread without
causing deadlock, provided that a call to globus_rmutex_unlock() is
called the same number of times as globus_rmutex_lock(). Once acquired,
all other threads calling this function will be blocked until the
mutex is completely unlocked.
- Parameters
-
rmutex | A pointer to the mutex to lock |
- Returns
- On success, globus_rmutex_init() increases the lock level for the mutex, blocks other threads trying to acquire the same mutex, and returns GLOBUS_SUCCESS; otherwise, it returns a non-zero error code.
References globus_cond_wait(), globus_mutex_lock(), globus_mutex_unlock(), globus_thread_equal(), and globus_thread_self().
Destroy a recursive mutex.
The globus_rmutex_destroy() function destroys a recursive mutex
If the mutex is currently locked, behavior is undefined.
- Parameters
-
- Returns
- GLOBUS_SUCCESS
References globus_cond_destroy(), and globus_mutex_destroy().