.TH "globus_mutex" 3 "Wed Feb 27 2019" "Version 18.2" "globus_common" \" -*- nroff -*-
.ad l
.nh
.SH NAME
globus_mutex \- Mutual Exclusion\&.  

.SH SYNOPSIS
.br
.PP
.SS "Data Structures"

.in +1c
.ti -1c
.RI "union \fBglobus_mutex_t\fP"
.br
.RI "Mutex\&. "
.ti -1c
.RI "union \fBglobus_mutexattr_t\fP"
.br
.RI "Mutex attribute\&. "
.ti -1c
.RI "struct \fBglobus_rmutex_t\fP"
.br
.RI "Recursive Mutex\&. "
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef int \fBglobus_rmutexattr_t\fP"
.br
.RI "Recursive mutex attribute\&. "
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "int \fBglobus_mutex_init\fP (\fBglobus_mutex_t\fP *mutex, \fBglobus_mutexattr_t\fP *attr)"
.br
.RI "Initialize a mutex\&. "
.ti -1c
.RI "int \fBglobus_mutex_destroy\fP (\fBglobus_mutex_t\fP *mutex)"
.br
.RI "Destroy a mutex\&. "
.ti -1c
.RI "int \fBglobus_mutex_lock\fP (\fBglobus_mutex_t\fP *mutex)"
.br
.RI "Lock a mutex\&. "
.ti -1c
.RI "int \fBglobus_mutex_unlock\fP (\fBglobus_mutex_t\fP *mutex)"
.br
.RI "Unlock a mutex\&. "
.ti -1c
.RI "int \fBglobus_mutex_trylock\fP (\fBglobus_mutex_t\fP *mutex)"
.br
.RI "Lock a mutex if it is not locked\&. "
.ti -1c
.RI "int \fBglobus_mutexattr_init\fP (\fBglobus_mutexattr_t\fP *attr)"
.br
.RI "Initialize a mutex attribute\&. "
.ti -1c
.RI "int \fBglobus_mutexattr_destroy\fP (\fBglobus_mutexattr_t\fP *attr)"
.br
.RI "Destroy a mutex attribute\&. "
.in -1c
.SS "Recursive Mutex"

.in +1c
.ti -1c
.RI "int \fBglobus_rmutex_init\fP (\fBglobus_rmutex_t\fP *rmutex, \fBglobus_rmutexattr_t\fP *rattr)"
.br
.RI "Initialize a recursive mutex\&. "
.ti -1c
.RI "int \fBglobus_rmutex_lock\fP (\fBglobus_rmutex_t\fP *rmutex)"
.br
.RI "Lock a recursive mutex\&. "
.ti -1c
.RI "int \fBglobus_rmutex_unlock\fP (\fBglobus_rmutex_t\fP *rmutex)"
.br
.RI "Unlock a recursive mutex\&. "
.ti -1c
.RI "int \fBglobus_rmutex_destroy\fP (\fBglobus_rmutex_t\fP *rmutex)"
.br
.RI "Destroy a recursive mutex\&. "
.in -1c
.SH "Detailed Description"
.PP 
Mutual Exclusion\&. 

The Globus runtime includes three portable, related mutual exclusion primitives that can be used in applications and libraries\&. These are
.IP "\(bu" 2
\fBglobus_mutex_t\fP: a non-recursive, non-shared lock
.IP "\(bu" 2
\fBglobus_rmutex_t\fP: a recursive non-shared lock
.IP "\(bu" 2
globus_rw_mutex_t: a reader-writer lock 
.PP

.SH "Function Documentation"
.PP 
.SS "int globus_mutex_destroy (\fBglobus_mutex_t\fP * mutex)"

.PP
Destroy a mutex\&. The \fBglobus_mutex_destroy()\fP function destroys the mutex pointed to by its \fImutex\fP parameter\&. After a mutex is destroyed it may no longer be used unless it is again initialized by \fBglobus_mutex_init()\fP\&. Behavior is undefined if \fBglobus_mutex_destroy()\fP is called with a pointer to a locked mutex\&.
.PP
\fBParameters:\fP
.RS 4
\fImutex\fP The mutex to destroy 
.RE
.PP
\fBReturns:\fP
.RS 4
On success, \fBglobus_mutex_destroy()\fP returns GLOBUS_SUCCESS\&. Otherwise, a non-zero implementation-specific error value is returned\&. 
.RE
.PP

.SS "int globus_mutex_init (\fBglobus_mutex_t\fP * mutex, \fBglobus_mutexattr_t\fP * attr)"

.PP
Initialize a mutex\&. The \fBglobus_mutex_init()\fP function creates a mutex variable that can be used for synchronization\&. Currently, the \fIattr\fP parameter is ignored\&.
.PP
\fBParameters:\fP
.RS 4
\fImutex\fP Pointer to the mutex to initialize\&. 
.br
\fIattr\fP Ignored\&.
.RE
.PP
\fBReturns:\fP
.RS 4
On success, \fBglobus_mutex_init()\fP initializes the mutex and returns GLOBUS_SUCCESS\&. Otherwise, a non-0 value is returned\&. 
.RE
.PP

.SS "int globus_mutex_lock (\fBglobus_mutex_t\fP * mutex)"

.PP
Lock a mutex\&. The \fBglobus_mutex_lock()\fP function locks the mutex pointed to by its \fImutex\fP parameter\&.
.PP
Upon successful return, the thread calling \fBglobus_mutex_lock()\fP has an exclusive lock on the resources protected by \fImutex\fP\&. Other threads calling \fBglobus_mutex_lock()\fP will wait until that thread later calls \fBglobus_mutex_unlock()\fP or \fBglobus_cond_wait()\fP 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\&.
.PP
\fBParameters:\fP
.RS 4
\fImutex\fP The mutex to lock\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
On success, \fBglobus_mutex_lock()\fP returns GLOBUS_SUCCESS\&. Otherwise, a non-zero implementation-specific error value is returned\&. 
.RE
.PP

.SS "int globus_mutex_trylock (\fBglobus_mutex_t\fP * mutex)"

.PP
Lock a mutex if it is not locked\&. The \fBglobus_mutex_trylock()\fP function locks the mutex pointed to by its \fImutex\fP parameter if no thread has already locked the mutex\&. If \fImutex\fP is locked, then \fBglobus_mutex_trylock()\fP returns EBUSY and does not block the current thread or lock the mutex\&. Upon successful return, the thread calling \fBglobus_mutex_trylock()\fP has an exclusive lock on the resources protected by \fImutex\fP\&. Other threads calling \fBglobus_mutex_lock()\fP will wait until that thread later calls \fBglobus_mutex_unlock()\fP or \fBglobus_cond_wait()\fP with that mutex\&.
.PP
\fBParameters:\fP
.RS 4
\fImutex\fP The mutex to lock\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
On success, \fBglobus_mutex_trylock()\fP returns GLOBUS_SUCCESS and locks the mutex\&. If another thread holds the lock, \fBglobus_mutex_trylock()\fP returns EBUSY\&. Otherwise, a non-zero implementation-specific error value is returned\&. 
.RE
.PP

.SS "int globus_mutex_unlock (\fBglobus_mutex_t\fP * mutex)"

.PP
Unlock a mutex\&. The \fBglobus_mutex_unlock()\fP function unlocks the mutex pointed to by its \fImutex\fP parameter\&. Upon successful return, the thread calling \fBglobus_mutex_unlock()\fP no longer has an exclusive lock on the resources protected by \fImutex\fP\&. Another thread calling \fBglobus_mutex_lock()\fP may be unblocked so that it may acquire the mutex\&. Behavior is undefined if globus_mutex_unlock is called with an unlocked mutex\&.
.PP
\fBParameters:\fP
.RS 4
\fImutex\fP The mutex to unlock\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
On success, \fBglobus_mutex_unlock()\fP returns GLOBUS_SUCCESS\&. Otherwise, a non-zero implementation-specific error value is returned\&. 
.RE
.PP

.SS "int globus_mutexattr_destroy (\fBglobus_mutexattr_t\fP * attr)"

.PP
Destroy a mutex attribute\&. The \fBglobus_mutexattr_destroy()\fP function destroys the mutex attribute structure pointed to by its \fIattr\fP parameter\&.
.PP
\fBParameters:\fP
.RS 4
\fIattr\fP Attribute structure to destroy\&.
.RE
.PP
\fBReturns:\fP
.RS 4
Upon success, \fBglobus_mutexattr_destroy()\fP returns GLOBUS_SUCCESS and modifies the attribute pointed to by \fIattr\fP\&. If an error occurs, \fBglobus_mutexattr_destroy()\fP returns an implementation-specific non-zero error code\&. 
.RE
.PP

.SS "int globus_mutexattr_init (\fBglobus_mutexattr_t\fP * attr)"

.PP
Initialize a mutex attribute\&. The \fBglobus_mutexattr_init()\fP function initializes the mutex attribute structure pointed to by its \fIattr\fP parameter\&. Currently there are no attribute values that can be set via this API, so there's no real use to calling this function\&.
.PP
\fBParameters:\fP
.RS 4
\fIattr\fP Attribute structure to initialize\&.
.RE
.PP
\fBReturns:\fP
.RS 4
Upon success, \fBglobus_mutexattr_init()\fP returns GLOBUS_SUCCESS and modifies the attribute pointed to by \fIattr\fP\&. If an error occurs, \fBglobus_mutexattr_init()\fP returns an implementation-specific non-zero error code\&. 
.RE
.PP

.SS "int globus_rmutex_destroy (\fBglobus_rmutex_t\fP * rmutex)"

.PP
Destroy a recursive mutex\&. The \fBglobus_rmutex_destroy()\fP function destroys a recursive mutex If the mutex is currently locked, behavior is undefined\&.
.PP
\fBParameters:\fP
.RS 4
\fIrmutex\fP Mutex to unlock
.RE
.PP
\fBReturns:\fP
.RS 4
GLOBUS_SUCCESS 
.RE
.PP

.SS "int globus_rmutex_init (\fBglobus_rmutex_t\fP * rmutex, \fBglobus_rmutexattr_t\fP * rattr)"

.PP
Initialize a recursive mutex\&. The \fBglobus_rmutex_init()\fP function initializes a recursive mutex, that is, one which may be locked multiple times by a single thread without causing deadlock\&. 
.PP
\fBParameters:\fP
.RS 4
\fIrmutex\fP A pointer to the mutex to initialize 
.br
\fIrattr\fP IGNORED
.RE
.PP
\fBReturns:\fP
.RS 4
On success, \fBglobus_rmutex_init()\fP initializes the mutex and returns GLOBUS_SUCCESS; otherwise, it returns a non-zero error code\&. 
.RE
.PP

.SS "int globus_rmutex_lock (\fBglobus_rmutex_t\fP * rmutex)"

.PP
Lock a recursive mutex\&. The \fBglobus_rmutex_lock()\fP function acquires the lock controlled by \fIrmutex\fP\&. This may be called multiple times in a single thread without causing deadlock, provided that a call to \fBglobus_rmutex_unlock()\fP is called the same number of times as \fBglobus_rmutex_lock()\fP\&. Once acquired, all other threads calling this function will be blocked until the mutex is completely unlocked\&.
.PP
\fBParameters:\fP
.RS 4
\fIrmutex\fP A pointer to the mutex to lock
.RE
.PP
\fBReturns:\fP
.RS 4
On success, \fBglobus_rmutex_init()\fP 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\&. 
.RE
.PP

.SS "int globus_rmutex_unlock (\fBglobus_rmutex_t\fP * rmutex)"

.PP
Unlock a recursive mutex\&. The \fBglobus_rmutex_unlock()\fP function decrements the lock count for the lock pointed to by \fIrmutex\fP\&. If the lock count is reduced to zero, it also unblocks a thread which is trying to acquire the lock if there is one\&.
.PP
\fBParameters:\fP
.RS 4
\fIrmutex\fP Mutex to unlock
.RE
.PP
\fBReturns:\fP
.RS 4
GLOBUS_SUCCESS 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for globus_common from the source code\&.