--- name: "globus_mutex" section: "3" platform: "linux" package: "libglobus-common-doc" version: "18.14-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/globus_mutex" --- # globus\_mutex(3) Mutual Exclusion - Mutual Exclusion. ## 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.