NAME

       globus_mutex - Mutual Exclusion

        - Mutual Exclusion.

SYNOPSIS

   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
           Recursive mutex attribute.

   Functions
       int globus_mutex_init (globus_mutex_t *mutex, globus_mutexattr_t *attr)
           Initialize a mutex.
       int globus_mutex_destroy (globus_mutex_t *mutex)
           Destroy a mutex.
       int globus_mutex_lock (globus_mutex_t *mutex)
           Lock a mutex.
       int globus_mutex_unlock (globus_mutex_t *mutex)
           Unlock a mutex.
       int globus_mutex_trylock (globus_mutex_t *mutex)
           Lock a mutex if it is not locked.
       int globus_mutexattr_init (globus_mutexattr_t *attr)
           Initialize a mutex attribute.
       int globus_mutexattr_destroy (globus_mutexattr_t *attr)
           Destroy a mutex attribute.

   Recursive Mutex
       int globus_rmutex_init (globus_rmutex_t *rmutex, globus_rmutexattr_t *rattr)
           Initialize a recursive mutex.
       int globus_rmutex_lock (globus_rmutex_t *rmutex)
           Lock a recursive mutex.
       int globus_rmutex_unlock (globus_rmutex_t *rmutex)
           Unlock a recursive mutex.
       int globus_rmutex_destroy (globus_rmutex_t *rmutex)
           Destroy a recursive mutex.

Detailed Description

       Mutual Exclusion.

       The Globus runtime includes three portable, related mutual exclusion primitives that can
       be used in applications and libraries. These are

       • globus_mutex_t: a non-recursive, non-shared lock

       • globus_rmutex_t: a recursive non-shared lock

       • globus_rw_mutex_t: a reader-writer lock

Function Documentation

   int globus_mutex_destroy (globus_mutex_t * mutex)
       Destroy a mutex. The globus_mutex_destroy() function destroys the mutex pointed to by its
       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_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_lock (globus_mutex_t * mutex)
       Lock a mutex. The globus_mutex_lock() function locks the mutex pointed to by its mutex
       parameter.

       Upon successful return, the thread calling globus_mutex_lock() has an exclusive lock on
       the resources protected by 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_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 mutex parameter if no thread has already locked the mutex. If 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 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_mutex_unlock (globus_mutex_t * mutex)
       Unlock a mutex. The globus_mutex_unlock() function unlocks the mutex pointed to by its
       mutex parameter. Upon successful return, the thread calling globus_mutex_unlock() no
       longer has an exclusive lock on the resources protected by 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_mutexattr_destroy (globus_mutexattr_t * attr)
       Destroy a mutex attribute. The globus_mutexattr_destroy() function destroys the mutex
       attribute structure pointed to by its 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_mutexattr_init (globus_mutexattr_t * attr)
       Initialize a mutex attribute. The globus_mutexattr_init() function initializes the mutex
       attribute structure pointed to by its 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_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
           rmutex Mutex to unlock

       Returns
           GLOBUS_SUCCESS

   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
           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. The globus_rmutex_lock() function acquires the lock controlled by
       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. The globus_rmutex_unlock() function decrements the lock count
       for the lock pointed to by 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

Author

       Generated automatically by Doxygen for globus_common from the source code.