Provided by: libglobus-common-doc_18.14-1.1build1_all bug

NAME

       globus_cond - Condition Variables

        - Condition Variables.

SYNOPSIS

   Data Structures
       union globus_cond_t
           Condition variable.
       union globus_condattr_t
           Condition variable attribute.

   Functions
       int globus_cond_init (globus_cond_t *cond, globus_condattr_t *attr)
           Initialize a condition variable

       The globus_cond_init() function creates a condition variable that can be used for event
       signalling between threads. "
   int globus_cond_destroy (globus_cond_t *cond)
       Destroy a condition variable.
   int globus_cond_wait (globus_cond_t *cond, globus_mutex_t *mutex)
       Wait for a condition to be signalled.
   int globus_cond_timedwait (globus_cond_t *cond, globus_mutex_t *mutex, globus_abstime_t
       *abstime)
       Wait for a condition to be signalled.
   int globus_cond_signal (globus_cond_t *cond)
       Signal a condition to a thread.
   int globus_cond_broadcast (globus_cond_t *cond)
       Signal a condition to multiple threads.
   int globus_condattr_init (globus_condattr_t *cond_attr)
       Initialize a condition variable attribute.
   int globus_condattr_destroy (globus_condattr_t *cond_attr)
       Destroy a condition attribute.
   int globus_condattr_setspace (globus_condattr_t *cond_attr, int space)
       Set callback space associated with a condition variable attribute

       The 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. "
   int globus_condattr_getspace (globus_condattr_t *cond_attr, int *space)
       Get callback space associated with a condition variable attribute

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

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
           cond A 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
           cond The 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 variable

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

       Parameters
           cond Pointer to the condition variable to initialize.
           attr Condition 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
           cond A 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
           cond The condition variable to wait for.
           mutex The mutex associated with the condition state.
           abstime The 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
           cond The condition variable to wait for.
           mutex The 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_attr Attribute 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 attribute

       The 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_attr Condition variable attribute to modify.
           space Pointer 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_attr Attribute 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 attribute

       The 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_attr Condition variable attribute to modify.
           space Callback 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.

Author

       Generated automatically by Doxygen for globus_common from the source code.