Mutual Exclusion
Collaboration diagram for Mutual Exclusion:

Data Structures

union  globus_mutex_t
 
union  globus_mutexattr_t
 
struct  globus_rmutex_t
 

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

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
mutexPointer to the mutex to initialize.
attrIgnored.
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.

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
mutexThe 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.

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
mutexThe 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.

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
mutexThe 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.

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
mutexThe 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.

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
attrAttribute 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.

The globus_mutexattr_destroy() function destroys the mutex attribute
structure pointed to by its @a attr parameter. 
Parameters
attrAttribute 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.

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
rmutexA pointer to the mutex to initialize
rattrIGNORED
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().

int globus_rmutex_lock ( globus_rmutex_t rmutex)

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
rmutexA 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().

int globus_rmutex_unlock ( globus_rmutex_t rmutex)

Unlock a recursive mutex.

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
rmutexMutex to unlock
Returns
GLOBUS_SUCCESS

References globus_cond_signal(), globus_mutex_lock(), globus_mutex_unlock(), globus_thread_equal(), and globus_thread_self().

int globus_rmutex_destroy ( globus_rmutex_t rmutex)

Destroy a recursive mutex.

The globus_rmutex_destroy() function destroys a recursive mutex
If the mutex is currently locked, behavior is undefined.
Parameters
rmutexMutex to unlock
Returns
GLOBUS_SUCCESS

References globus_cond_destroy(), and globus_mutex_destroy().


about globus | globus toolkit | dev.globus

Comments? webmaster@globus.org