Mutual Exclusion(3) globus common Mutual Exclusion(3)
NAME
Mutual Exclusion -
Data Structures
union globus_mutex_t
Mutex.
union globus_mutexattr_t
Mutex attribute.
struct globus_rmutex_t
Recursive Mutex.
Typedefs
typedef int globus_rmutexattr_t
Functions
int globus_mutex_init (globus_mutex_t *mutex, globus_mutexattr_t *attr)
int globus_mutex_destroy (globus_mutex_t *mutex)
int globus_mutex_lock (globus_mutex_t *mutex)
int globus_mutex_unlock (globus_mutex_t *mutex)
int globus_mutex_trylock (globus_mutex_t *mutex)
int globus_mutexattr_init (globus_mutexattr_t *attr)
int globus_mutexattr_destroy (globus_mutexattr_t *attr)
Recursive Mutex
int globus_rmutex_init (globus_rmutex_t *rmutex, globus_rmutexattr_t *rattr)
int globus_rmutex_lock (globus_rmutex_t *rmutex)
int globus_rmutex_unlock (globus_rmutex_t *rmutex)
int globus_rmutex_destroy (globus_rmutex_t *rmutex)
Detailed Description
The Globus runtime includes three portable, related mutual exclusion primitives that can be used in applications and libraries. These are
o globus_mutex_t: a non-recursive, non-shared lock
o globus_rmutex_t: a recursive non-shared lock
o globus_rw_mutex_t: a reader-writer lock
Typedef Documentation
typedef int globus_rmutexattr_t
Recursive mutex attribute.
Function Documentation
int globus_mutex_init (globus_mutex_t *mutex, globus_mutexattr_t *attr)
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.
int globus_mutex_destroy (globus_mutex_t *mutex)
Destroy a mutex. .PP
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.
int globus_mutex_lock (globus_mutex_t *mutex)
Lock a mutex. .PP
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:
mutex The mutex to lock.
Returns:
On success, globus_mutex_lock() returns GLOBUS_SUCCESS. Otherwise, a non-zero implementation-specific error value is returned.
int globus_mutex_unlock (globus_mutex_t *mutex)
Unlock a mutex. .PP
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.
int globus_mutex_trylock (globus_mutex_t *mutex)
Lock a mutex if it is not locked. .PP
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:
mutex The mutex to lock.
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.
int globus_mutexattr_init (globus_mutexattr_t *attr)
Initialize a mutex attribute. .PP
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.
int globus_mutexattr_destroy (globus_mutexattr_t *attr)
Destroy a mutex attribute. .PP
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.
int globus_rmutex_init (globus_rmutex_t *rmutex, globus_rmutexattr_t *rattr)
Initialize a recursive mutex. .PP
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.
int globus_rmutex_lock (globus_rmutex_t *rmutex)
Lock a recursive mutex. .PP
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.
int globus_rmutex_unlock (globus_rmutex_t *rmutex)
Unlock a recursive mutex. .PP
The globus_rmutex_unlock() function decrements the lock count for
the lock pointed to by @a rmutex. If the lock count is reduced to
zero, it also unblocks a thread which is trying to acquire the lock
if there is one.
Parameters:
rmutex Mutex to unlock
Returns:
GLOBUS_SUCCESS
int globus_rmutex_destroy (globus_rmutex_t *rmutex)
Destroy a recursive mutex. .PP
The globus_rmutex_destroy() function destroys a recursive mutex
If the mutex is currently locked, behavior is undefined.
Parameters:
rmutex Mutex to unlock
Returns:
GLOBUS_SUCCESS
Author
Generated automatically by Doxygen for globus common from the source code.
Version 14.7 Tue Nov 27 2012 Mutual Exclusion(3)