Grid Community Toolkit  6.2.1629922860 (tag: v6.2.20210826)
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Data Structures | Functions
Condition Variables

Condition Variables. More...

Data Structures

union  globus_cond_t
 Condition variable. More...
 
union  globus_condattr_t
 Condition variable attribute. More...
 

Functions

int globus_cond_init (globus_cond_t *cond, globus_condattr_t *attr)
 Initialize a condition variableThe globus_cond_init() function creates a condition variable that can be used for event signalling between threads. More...
 
int globus_cond_destroy (globus_cond_t *cond)
 Destroy a condition variable. More...
 
int globus_cond_wait (globus_cond_t *cond, globus_mutex_t *mutex)
 Wait for a condition to be signalled. More...
 
int globus_cond_timedwait (globus_cond_t *cond, globus_mutex_t *mutex, globus_abstime_t *abstime)
 Wait for a condition to be signalled. More...
 
int globus_cond_signal (globus_cond_t *cond)
 Signal a condition to a thread. More...
 
int globus_cond_broadcast (globus_cond_t *cond)
 Signal a condition to multiple threads. More...
 
int globus_condattr_init (globus_condattr_t *cond_attr)
 Initialize a condition variable attribute. More...
 
int globus_condattr_destroy (globus_condattr_t *cond_attr)
 Destroy a condition attribute. More...
 
int globus_condattr_setspace (globus_condattr_t *cond_attr, int space)
 Set callback space associated with a condition variable attributeThe globus_condattr_setspace() 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 Callback Spaces for more information on callback spaces. More...
 
int globus_condattr_getspace (globus_condattr_t *cond_attr, int *space)
 Get callback space associated with a condition variable attributeThe globus_condattr_getspace() function copies the value of the callback space associated with a condition variable attribute to the integer pointed to by the space parameter. More...
 

Detailed Description

Condition Variables.

The globus_cond_t 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.

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.

Function Documentation

int globus_cond_broadcast ( globus_cond_t cond)

Signal a condition to multiple threads.

The globus_cond_signal() function signals a condition as occurring. This will unblock all threads waiting for that condition.

Parameters
condA pointer to the condition variable to signal.
Returns
Upon success, globus_cond_broadcast() returns GLOBUS_SUCCESS. If an error occurs, globus_cond_broadcast() returns an implementation-specific non-zero error code.
int globus_cond_destroy ( globus_cond_t cond)

Destroy a condition variable.

The globus_cond_destroy() function destroys the condition variable pointed to by its cond parameter. After a condition variable is destroyed it may no longer be used unless it is again initialized by globus_cond_init().

Parameters
condThe condition variable to destroy.
Returns
On success, globus_cond_destroy() returns GLOBUS_SUCCESS. Otherwise, a non-zero implementation-specific error value is returned.
int globus_cond_init ( globus_cond_t cond,
globus_condattr_t attr 
)

Initialize a condition variableThe globus_cond_init() function creates a condition variable that can be used for event signalling between threads.

Parameters
condPointer to the condition variable to initialize.
attrCondition variable attributes.
Returns
On success, globus_cond_init() initializes the condition variable and returns GLOBUS_SUCCESS. Otherwise, a non-0 value is returned.
int globus_cond_signal ( globus_cond_t cond)

Signal a condition to a thread.

The globus_cond_signal() function signals a condition as occurring. This will unblock at least one thread waiting for that condition.

Parameters
condA pointer to the condition variable to signal.
Returns
Upon success, globus_cond_signal() returns GLOBUS_SUCCESS. If an error occurs, globus_cond_signal() returns an implementation-specific non-zero error code.
int globus_cond_timedwait ( globus_cond_t cond,
globus_mutex_t mutex,
globus_abstime_t *  abstime 
)

Wait for a condition to be signalled.

The globus_cond_timedwait() function atomically unlocks the mutex pointed to by the mutex parameter and blocks the current thread until either the condition variable pointed to by cond is signalled by another thread or the current time exceeds the value pointed to by the 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 mutex variable unlocked.

Parameters
condThe condition variable to wait for.
mutexThe mutex associated with the condition state.
abstimeThe absolute time to wait until.
Returns
On success, globus_cond_timedwait() unlocks the mutex and blocks the current thread until it has been signalled, returning GLOBUS_SUCCES. If a timeout occurs before signal, globus_cond_timedwait() unlocks the mutex and returns ETIMEDOUT. Otherwise, globus_cond_timedwait() returns an implementation-specific non-zero error value.
int globus_cond_wait ( globus_cond_t cond,
globus_mutex_t mutex 
)

Wait for a condition to be signalled.

The globus_cond_wait() function atomically unlocks the mutex pointed to by the mutex parameter and blocks the current thread until the condition variable pointed to by 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 mutex variable unlocked.

Parameters
condThe condition variable to wait for.
mutexThe mutex associated with the condition state.
Returns
On success, globus_cond_wait() unlocks the mutex and blocks the current thread until it has been signalled, returning GLOBUS_SUCCES. Otherwise, globus_cond_wait() returns an implementation-specific non-zero error value.
int globus_condattr_destroy ( globus_condattr_t cond_attr)

Destroy a condition attribute.

The globus_condattr_destroy() function destroys the condition variable attribute structure pointed to by its cond_attr parameter.

Parameters
cond_attrAttribute structure to destroy.
Returns
Upon success, globus_condattr_destroy() returns GLOBUS_SUCCESS and modifies the attribute pointed to by cond_attr. If an error occurs, globus_condattr_destroy() returns an implementation-specific non-zero error code.
int globus_condattr_getspace ( globus_condattr_t cond_attr,
int *  space 
)

Get callback space associated with a condition variable attributeThe globus_condattr_getspace() function copies the value of the callback space associated with a condition variable attribute to the integer pointed to by the space parameter.

Parameters
cond_attrCondition variable attribute to modify.
spacePointer to an integer to be set to point to the callback space associated with cond_attr.
Returns
On success, globus_condattr_getspace() returns GLOBUS_SUCCESS and modifies the value pointed to by space to refer to the callback space associated with cond_attr. If an error occurs, globus_condattr_getspace() returns an implementation-specific non-zero error code.
int globus_condattr_init ( globus_condattr_t cond_attr)

Initialize a condition variable attribute.

The globus_condattr_init() function initializes the condition variable attribute structure pointed to by its cond_attr parameter to the system default values.

Parameters
cond_attrAttribute structure to initialize.
Returns
Upon success, globus_condattr_init() returns GLOBUS_SUCCESS and modifies the attribute pointed to by cond_attr. If an error occurs, globus_condattr_init() returns an implementation-specific non-zero error code.
int globus_condattr_setspace ( globus_condattr_t cond_attr,
int  space 
)

Set callback space associated with a condition variable attributeThe globus_condattr_setspace() 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 Callback Spaces for more information on callback spaces.

Parameters
cond_attrCondition variable attribute to modify.
spaceCallback space to associate with the attribute.
Returns
On success, globus_condattr_setspace() returns GLOBUS_SUCCESS and adds a reference to the callback space to the condition variable attribute. If an error occurs, globus_condattr_setspace() returns an implementation-specific non-zero error code.