Provided by: libglobus-common-doc_14.10-2_all bug

NAME

       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

       • 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

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.

       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.

       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.

       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.

       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.

       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.

       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.

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

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

   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:
           rmutex Mutex 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:
           rmutex Mutex to unlock

       Returns:
           GLOBUS_SUCCESS

       References globus_cond_destroy(), and globus_mutex_destroy().

Author

       Generated automatically by Doxygen for globus common from the source code.