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

NAME

       globus_thread - Threading

        - Portable Thread Abstraction.

SYNOPSIS

   Modules
       Mutual Exclusion
           Mutual Exclusion.
       Condition Variables
           Condition Variables.
       Thread-Specific Storage
           Thread-Specific Storage.
       One-time execution
           One-time execution.

   Data Structures
       union globus_thread_t
           Thread ID.
       union globus_threadattr_t
           Thread attributes.
       union globus_thread_key_t
           Thread-specific data key.

   Macros
       #define GLOBUS_THREAD_CANCEL_DISABLE   0
           Disable thread cancellation value.
       #define GLOBUS_THREAD_CANCEL_ENABLE   1
           Enable thread cancellation value.
       #define GLOBUS_THREAD_MODULE
           Thread Module.

   Typedefs
       typedef void(* globus_thread_key_destructor_func_t) (void *value)
           Thread-specific data destructor.

   Functions
       int globus_thread_set_model (const char *model)
           Select threading model for an application.
       int globus_thread_create (globus_thread_t *thread, globus_threadattr_t *attr,
           globus_thread_func_t func, void *user_arg)
           Create a new thread.
       void globus_thread_yield (void)
           Yield execution to another thread.
       void globus_thread_exit (void *value)
           Terminate the current thread.
       int globus_thread_sigmask (int how, const sigset_t *new_mask, sigset_t *old_mask)
           Modify the current thread's signal mask.
       int globus_thread_kill (globus_thread_t thread, int sig)
           Send a signal to a thread.
       globus_thread_t globus_thread_self (void)
           Determine the current thread's ID.
       globus_bool_t globus_thread_equal (globus_thread_t thread1, globus_thread_t thread2)
           Check whether thread identifiers match.
       globus_bool_t globus_thread_preemptive_threads (void)
           Indicate whether the active thread model supports preemption.
       globus_bool_t globus_i_am_only_thread (void)
           Determine if threads are supported.
       void * globus_thread_cancellable_func (void *(*func)(void *), void *arg,
           void(*cleanup_func)(void *), void *cleanup_arg, globus_bool_t execute_cleanup)
           Execute a function with thread cleanup in case of cancellation.
       int globus_thread_cancel (globus_thread_t thr)
           Cancel a thread.
       void globus_thread_testcancel (void)
           Thread cancellation point.
       int globus_thread_setcancelstate (int state, int *oldstate)
           Set the thread's cancellable state.

Detailed Description

       Portable Thread Abstraction.

       The Globus runtime includes support for portably creating threads on POSIX and Windows
       systems. It also provides a callback-driven system for applications that may use threads
       but don't require them. The Globus Thread API is modeled closely after the POSIX threads
       API.

       Applications can choose whether to run as threaded or non-threaded at runtime by either
       setting the GLOBUS_THREAD_MODEL environment variable or calling the
       globus_thread_set_model() function prior to activating any Globus modules.

       The Globus thread system provides primitives for mutual exclusion (globus_mutex_t,
       globus_rmutex_t, globus_rw_mutex_t), event synchronization (globus_cond_t), one-time
       execution (globus_once_t), and threading (globus_thread_t).

       In non-threaded operation, globus_cond_wait() and its variants will poll the callback
       queue and I/O system to allow event-driven programs to run in the absence of threads. The
       globus_thread_create() function will fail in that model. Other primitive operations will
       return success but not provide any thread exclusion as there is only one thread.

Macro Definition Documentation

   #define GLOBUS_THREAD_CANCEL_DISABLE   0
       Disable thread cancellation value.

       See also
           globus_thread_setcancelstate()

   #define GLOBUS_THREAD_CANCEL_ENABLE   1
       Enable thread cancellation value.

       See also
           globus_thread_setcancelstate()

Function Documentation

   globus_bool_t globus_i_am_only_thread (void)
       Determine if threads are supported. The globus_i_am_only_thread() function determines
       whether multiple threads may be running in this process.

       Returns
           The globus_i_am_only_thread() function returns GLOBUS_TRUE if the current thread model
           is the 'none' thread model; GLOBUS_FALSE otherwise.

   int globus_thread_cancel (globus_thread_t thr)
       Cancel a thread. The globus_thread_cancel() function cancels the thread with the
       identifier thr if it is still executing. If it is running with a cancellation cleanup
       stack, the functions in that stack are executed. The target thread's cancel state
       determines when the cancellation is delivered.

       Parameters
           thr The id of the thread to cancel

       Returns
           On success, the globus_thread_cancel() function delivers the cancellation to the
           target thread and returns GLOBUS_SUCCESS. If an error occurs, globus_thread_cancel()
           returns an implementation-specific non-zero error value.

   void * globus_thread_cancellable_func (void *(*)(void *) func, void * arg, void(*)(void *)
       cleanup_func, void * cleanup_arg, globus_bool_t execute_cleanup)
       Execute a function with thread cleanup in case of cancellation. The
       globus_thread_cancellable_func() function provides an interface to POSIX thread
       cancellation points that does not rely on preprocessor macros. It is roughly equivalent to

       pthread_cleanup_push(cleanup_func, cleanup_arg);
       (*func)(arg);
       pthread_cleanup_pop(execute_cleanup)

       Parameters
           func Pointer to a function which may be cancelled.
           arg Parameter to the func function.
           cleanup_func Pointer to a function to execute if thread cancellation occurs during
           func.
           cleanup_arg Parameter to the cleanup_func function.
           execute_cleanup Flag indicating whether the function pointed to by cleanup_func should
           be executed after func completes even if it is not cancelled.

       Returns
           globus_thread_cancellable_func() returns the value returned by func.

   int globus_thread_create (globus_thread_t * thread, globus_threadattr_t * attr,
       globus_thread_func_t func, void * user_arg)
       Create a new thread. The globus_thread_create() function creates a new thread of execution
       in the current process to run the function pointed to by the func parameter passed the
       user_arg value as its only parameter. This new thread will be detached, so that storage
       associated with the thread will be automatically reclaimed by the operating system. A
       thread identifier will be copied to the value pointed by the thread parameter if it is
       non-NULL. The caller may use this thread identifier to signal or cancel this thread. The
       attr parameter is ignored by this function. If the 'none' threading model is used by an
       application, then this function will always fail. One alternative that will work both with
       and without threads is to use the functions in the Globus Callback API .

       Parameters
           thread Pointer to a variable to contain the new thread's identifier.
           attr Ignored
           func Pointer to a function to start in the new thread.
           user_arg Argument to the new thread's function.

       Returns
           On success, globus_thread_create() will start a new thread, invoking
           (*func)(user_arg), modify the value pointed to by the thread parameter to contain the
           new thread's identifier and return GLOBUS_SUCCESS. If an error occurs, then the value
           of thread is undefined and globus_thread_create() returns an implementation-specific
           non-zero error value.

   globus_bool_t globus_thread_equal (globus_thread_t thread1, globus_thread_t thread2)
       Check whether thread identifiers match. The globus_thread_equal() function checks whether
       the thread identifiers passed as the thread1 and thread2 parameters refer to the same
       thread. If so, globus_thread_equal() returns GLOBUS_TRUE; otherwise GLOBUS_FALSE.

       Parameters
           thread1 Thread identifier to compare.
           thread2 Thread identifier to compare.

       Return values
           GLOBUS_TRUE thread1 and thread2 refer to the same thread.
           GLOBUS_FALSE thread1 and thread2 do not refer to the same thread.

   void globus_thread_exit (void * value)
       Terminate the current thread. The globus_thread_exit() terminates the current thread with
       the value passed to it. This function does not return.

   int globus_thread_kill (globus_thread_t thread, int sig)
       Send a signal to a thread. The globus_thread_kill() function sends the signal specified by
       the sig number to the thread whose ID matches the thread parameter. Depending on the
       signal mask of that thread, this may result in a signal being delivered or not, and
       depending on the process's signal actions, a signal handler, termination, or no operation
       will occur in that thread.

       Parameters
           thread The thread identifier of the thread to signal.
           sig The signal to send to the thread.

       Returns
           On success, globus_thread_kill() queues the signal for delivery to the specified
           thread and returns GLOBUS_SUCCESS. If an error occurs, globus_thread_kill() returns an
           implementation-specific non-zero error value.

   globus_bool_t globus_thread_preemptive_threads (void)
       Indicate whether the active thread model supports preemption.

       Returns
           The globus_thread_preemptive_threads() function returns GLOBUS_TRUE if the current
           thread model supports thread preemption; otherwise it returns GLOBUS_FALSE.

   globus_thread_t globus_thread_self (void)
       Determine the current thread's ID. The globus_thread_self() function returns the thread
       identifier of the current thread. This value is unique among all threads which are running
       at any given time.

       Returns
           The globus_thread_self() function returns the current thread's ID.

   int globus_thread_set_model (const char * model)
       Select threading model for an application. The globus_thread_set_model() function selects
       which runtime model the current application will use. By default, the Globus runtime uses
       a non-threaded model. Additional models may be available based on system support: pthread,
       or windows. This function must be called prior to activating any globus module, as it
       changes how certain functions (like globus_mutex_lock() and globus_cond_wait()) behave.
       This function overrides the value set by the GLOBUS_THREAD_MODEL environment variable.

       The globus_thread_set_model() function will fail if a Globus module has been activated
       already.

       Parameters
           model The name of the thread model to use. Depending on operating system capabilities,
           this may be 'none', 'pthread', 'windows', or some other custom thread implementation.
           The corresponding libtool module 'libglobus_thread_pthread.la' or
           'libglobus_thread_windows.la' must be installed on the system for it to be used.

       Returns
           On success, globus_thread_set_model() sets the name of the thread model to use and
           returns GLOBUS_SUCCESS. If an error occurs, then globus_thread_set_model() returns
           GLOBUS_FAILURE.

   int globus_thread_setcancelstate (int state, int * oldstate)
       Set the thread's cancellable state. The globus_thread_setcancelstate() function sets the
       current cancellation state to either GLOBUS_THREAD_CANCEL_DISABLE or
       GLOBUS_THREAD_CANCEL_ENABLE, do control whether globus_thread_cancel() is able to cancel
       this thread.

       Parameters
           state The desired cancellation state. If the value is GLOBUS_THREAD_CANCEL_DISABLE,
           then cancellation will be disabled for this thread. If the value is
           GLOBUS_THREAD_CANCEL_ENABLE, then cancellation will be enabled for this thread.
           oldstate A pointer to a value which will be set to the value of the thread's
           cancellation state when this function call began. This may be NULL if the caller is
           not interested in the previous value.

       Returns
           On success, the globus_thread_setcancelstate() function modifies the thread
           cancellation state, modifies oldstate (if non-NULL) to the value of its previous
           state, and returns GLOBUS_SUCCESS. If an error occurs, globus_thread_setcancelstate()
           returns an implementation-specific non-zero error value.

   int globus_thread_sigmask (int how, const sigset_t * new_mask, sigset_t * old_mask)
       Modify the current thread's signal mask. The globus_thread_sigmask() function modifies the
       current thread's signal mask and returns the old value of the signal mask in the value
       pointed to by the old_mask parameter. The how parameter can be one of SIG_BLOCK,
       SIG_UNBLOCK, or SIG_SETMASK to control how the signal mask is modified.

       Parameters
           how Flag indicating how to interpret new_mask if it is non-NULL. If how is SIG_BLOCK,
           then all signals in new_mask are blocked, as well as any which were previously
           blocked. If how is SIG_UNBLOCK, then all signals in which were previously blocked in
           new_mask are unblocked. If how is SIG_SETMASK, then the old signal mask is replaced
           with the value of new_mask.
           new_mask Set of signals to block or unblock, based on the how parameter.
           old_mask A pointer to be set to the old signal mask associated with the current
           thread.

       Returns
           On success, globus_thread_sigmask() modifies the signal mask, modifies the value
           pointed to by old_mask with the signal mask prior to this function's execution and
           returns GLOBUS_SUCCESS. If an error occurs, globus_thread_sigmask() returns an
           implementation-specific non-zero error value.

   void globus_thread_testcancel (void)
       Thread cancellation point. The globus_thread_testcancel() function acts as a cancellation
       point for the current thread. If a thread has called globus_thread_cancel() and
       cancellation is enabled, this will cause the thread to be cancelled and any functions on
       the thread's cleanup stack to be executed. This function will not return if the thread is
       cancelled.

   void globus_thread_yield (void)
       Yield execution to another thread. The globus_thread_yield() function yields execution to
       other threads which are ready for execution. The current thread may continue to execute if
       there are no other threads in the system's ready queue.

Author

       Generated automatically by Doxygen for globus_common from the source code.