.TH "Condition Variables" 3 "Tue Nov 27 2012" "Version 14.7" "globus common" \" -*- nroff -*-
.ad l
.nh
.SH NAME
Condition Variables \- 
.SS "Data Structures"

.in +1c
.ti -1c
.RI "union \fBglobus_cond_t\fP"
.br
.RI "\fICondition variable\&. \fP"
.ti -1c
.RI "union \fBglobus_condattr_t\fP"
.br
.RI "\fICondition variable attribute\&. \fP"
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "int \fBglobus_cond_init\fP (\fBglobus_cond_t\fP *cond, \fBglobus_condattr_t\fP *attr)"
.br
.ti -1c
.RI "int \fBglobus_cond_destroy\fP (\fBglobus_cond_t\fP *cond)"
.br
.ti -1c
.RI "int \fBglobus_cond_wait\fP (\fBglobus_cond_t\fP *cond, \fBglobus_mutex_t\fP *mutex)"
.br
.ti -1c
.RI "int \fBglobus_cond_timedwait\fP (\fBglobus_cond_t\fP *cond, \fBglobus_mutex_t\fP *mutex, globus_abstime_t *abstime)"
.br
.ti -1c
.RI "int \fBglobus_cond_signal\fP (\fBglobus_cond_t\fP *cond)"
.br
.ti -1c
.RI "int \fBglobus_cond_broadcast\fP (\fBglobus_cond_t\fP *cond)"
.br
.ti -1c
.RI "int \fBglobus_condattr_init\fP (\fBglobus_condattr_t\fP *cond_attr)"
.br
.ti -1c
.RI "int \fBglobus_condattr_destroy\fP (\fBglobus_condattr_t\fP *cond_attr)"
.br
.ti -1c
.RI "int \fBglobus_condattr_setspace\fP (\fBglobus_condattr_t\fP *cond_attr, int space)"
.br
.ti -1c
.RI "int \fBglobus_condattr_getspace\fP (\fBglobus_condattr_t\fP *cond_attr, int *space)"
.br
.in -1c
.SH "Detailed Description"
.PP 
The \fBglobus_cond_t\fP provides condition variables for signalling events between threads interested in particular state\&. One or many threads may wait on a condition variable until it is signalled, at which point they can attempt to lock a mutex related to that condition's state and process the event\&.
.PP
In a non-threaded model, the condition variable wait operations are used to poll the event driver to handle any operations that have been scheduled for execution by the globus_callback system or I/O system\&. In this way, applications written to use those systems to handle nonblocking operations will work with either a threaded or nonthreaded runtime choice\&. 
.SH "Function Documentation"
.PP 
.SS "int globus_cond_init (\fBglobus_cond_t\fP *cond, \fBglobus_condattr_t\fP *attr)"

.PP
Initialize a condition variable
.PP
The \fBglobus_cond_init()\fP function creates a condition variable that can be used for event signalling between threads\&. \fBParameters:\fP
.RS 4
\fIcond\fP Pointer to the condition variable to initialize\&. 
.br
\fIattr\fP Condition variable attributes\&.
.RE
.PP
\fBReturns:\fP
.RS 4
On success, \fBglobus_cond_init()\fP initializes the condition variable and returns GLOBUS_SUCCESS\&. Otherwise, a non-0 value is returned\&. 
.RE
.PP

.SS "int globus_cond_destroy (\fBglobus_cond_t\fP *cond)"

.PP
Destroy a condition variable\&. .PP
.nf
The globus_cond_destroy() function destroys the condition variable
pointed to by its @a cond parameter. After a condition variable is
destroyed it may no longer be used
unless it is again initialized by globus_cond_init(). 
.fi
.PP
.PP
\fBParameters:\fP
.RS 4
\fIcond\fP The condition variable to destroy\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
On success, \fBglobus_cond_destroy()\fP returns GLOBUS_SUCCESS\&. Otherwise, a non-zero implementation-specific error value is returned\&. 
.RE
.PP

.SS "int globus_cond_wait (\fBglobus_cond_t\fP *cond, \fBglobus_mutex_t\fP *mutex)"

.PP
Wait for a condition to be signalled\&. .PP
.nf
The globus_cond_wait() function atomically unlocks the mutex pointed to
by the @a mutex parameter and blocks the current thread until the
condition variable pointed to by @a cond is signalled by either
globus_cond_signal() or globus_cond_broadcast(). Behavior is undefined
if globus_cond_wait() is called with the mutex pointed to by the @a
mutex variable unlocked.
.fi
.PP
.PP
\fBParameters:\fP
.RS 4
\fIcond\fP The condition variable to wait for\&. 
.br
\fImutex\fP The mutex associated with the condition state\&.
.RE
.PP
\fBReturns:\fP
.RS 4
On success, \fBglobus_cond_wait()\fP unlocks the mutex and blocks the current thread until it has been signalled, returning GLOBUS_SUCCES\&. Otherwise, \fBglobus_cond_wait()\fP returns an implementation-specific non-zero error value\&. 
.RE
.PP

.SS "int globus_cond_timedwait (\fBglobus_cond_t\fP *cond, \fBglobus_mutex_t\fP *mutex, globus_abstime_t *abstime)"

.PP
Wait for a condition to be signalled\&. .PP
.nf
The globus_cond_timedwait() function atomically unlocks the mutex
pointed to by the @a mutex parameter and blocks the current thread until
either the condition variable pointed to by @a cond is signalled by
another thread or the current time exceeds the value pointed to by the
@a abstime parameter. If the timeout occurs before the condition is
signalled, globus_cond_timedwait() returns ETIMEDOUT. Behavior is
undefined if globus_cond_timedwait() is called with the mutex pointed to
by the @a mutex variable unlocked.
.fi
.PP
.PP
\fBParameters:\fP
.RS 4
\fIcond\fP The condition variable to wait for\&. 
.br
\fImutex\fP The mutex associated with the condition state\&. 
.br
\fIabstime\fP The absolute time to wait until\&.
.RE
.PP
\fBReturns:\fP
.RS 4
On success, \fBglobus_cond_timedwait()\fP unlocks the mutex and blocks the current thread until it has been signalled, returning GLOBUS_SUCCES\&. If a timeout occurs before signal, \fBglobus_cond_timedwait()\fP unlocks the mutex and returns ETIMEDOUT\&. Otherwise, \fBglobus_cond_timedwait()\fP returns an implementation-specific non-zero error value\&. 
.RE
.PP

.SS "int globus_cond_signal (\fBglobus_cond_t\fP *cond)"

.PP
Signal a condition to a thread\&. .PP
.nf
The globus_cond_signal() function signals a condition as occurring.
This will unblock at least one thread waiting for that condition.
.fi
.PP
.PP
\fBParameters:\fP
.RS 4
\fIcond\fP A pointer to the condition variable to signal\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Upon success, \fBglobus_cond_signal()\fP returns GLOBUS_SUCCESS\&. If an error occurs, \fBglobus_cond_signal()\fP returns an implementation-specific non-zero error code\&. 
.RE
.PP

.SS "int globus_cond_broadcast (\fBglobus_cond_t\fP *cond)"

.PP
Signal a condition to multiple threads\&. .PP
.nf
The globus_cond_signal() function signals a condition as occurring.
This will unblock all threads waiting for that condition.
.fi
.PP
.PP
\fBParameters:\fP
.RS 4
\fIcond\fP A pointer to the condition variable to signal\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Upon success, \fBglobus_cond_broadcast()\fP returns GLOBUS_SUCCESS\&. If an error occurs, \fBglobus_cond_broadcast()\fP returns an implementation-specific non-zero error code\&. 
.RE
.PP

.SS "int globus_condattr_init (\fBglobus_condattr_t\fP *cond_attr)"

.PP
Initialize a condition variable attribute\&. .PP
.nf
The globus_condattr_init() function initializes the condition variable
attribute structure pointed to by its @a cond_attr parameter to the
system default values.
.fi
.PP
.PP
\fBParameters:\fP
.RS 4
\fIcond_attr\fP Attribute structure to initialize\&.
.RE
.PP
\fBReturns:\fP
.RS 4
Upon success, \fBglobus_condattr_init()\fP returns GLOBUS_SUCCESS and modifies the attribute pointed to by \fIcond_attr\fP\&. If an error occurs, \fBglobus_condattr_init()\fP returns an implementation-specific non-zero error code\&. 
.RE
.PP

.SS "int globus_condattr_destroy (\fBglobus_condattr_t\fP *cond_attr)"

.PP
Destroy a condition attribute\&. .PP
.nf
The globus_condattr_destroy() function destroys the condition variable
attribute structure pointed to by its @a cond_attr parameter. 
.fi
.PP
.PP
\fBParameters:\fP
.RS 4
\fIcond_attr\fP Attribute structure to destroy\&.
.RE
.PP
\fBReturns:\fP
.RS 4
Upon success, \fBglobus_condattr_destroy()\fP returns GLOBUS_SUCCESS and modifies the attribute pointed to by \fIcond_attr\fP\&. If an error occurs, \fBglobus_condattr_destroy()\fP returns an implementation-specific non-zero error code\&. 
.RE
.PP

.SS "int globus_condattr_setspace (\fBglobus_condattr_t\fP *cond_attr, intspace)"

.PP
Set callback space associated with a condition variable attribute
.PP
The \fBglobus_condattr_setspace()\fP function sets the callback space to use with condition variables created with this attribute\&. Callback spaces are used to control how callbacks are issued to different threads\&. See \fBCallback Spaces \fP for more information on callback spaces\&.
.PP
\fBParameters:\fP
.RS 4
\fIcond_attr\fP Condition variable attribute to modify\&. 
.br
\fIspace\fP Callback space to associate with the attribute\&.
.RE
.PP
\fBReturns:\fP
.RS 4
On success, \fBglobus_condattr_setspace()\fP returns GLOBUS_SUCCESS and adds a reference to the callback space to the condition variable attribute\&. If an error occurs, \fBglobus_condattr_setspace()\fP returns an implementation-specific non-zero error code\&. 
.RE
.PP

.SS "int globus_condattr_getspace (\fBglobus_condattr_t\fP *cond_attr, int *space)"

.PP
Get callback space associated with a condition variable attribute
.PP
The \fBglobus_condattr_getspace()\fP function copies the value of the callback space associated with a condition variable attribute to the integer pointed to by the \fIspace\fP parameter\&. \fBParameters:\fP
.RS 4
\fIcond_attr\fP Condition variable attribute to modify\&. 
.br
\fIspace\fP Pointer to an integer to be set to point to the callback space associated with cond_attr\&.
.RE
.PP
\fBReturns:\fP
.RS 4
On success, \fBglobus_condattr_getspace()\fP returns GLOBUS_SUCCESS and modifies the value pointed to by \fIspace\fP to refer to the callback space associated with \fIcond_attr\fP\&. If an error occurs, \fBglobus_condattr_getspace()\fP returns an implementation-specific non-zero error code\&. 
.RE
.PP

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