.TH "globus_thread" 3 "Version 18.14" "globus_common" \" -*- nroff -*- .ad l .nh .SH NAME globus_thread \- Threading .PP \- Portable Thread Abstraction\&. .SH SYNOPSIS .br .PP .SS "Modules" .in +1c .ti -1c .RI "\fBMutual Exclusion\fP" .br .RI "Mutual Exclusion\&. " .ti -1c .RI "\fBCondition Variables\fP" .br .RI "Condition Variables\&. " .ti -1c .RI "\fBThread\-Specific Storage\fP" .br .RI "Thread-Specific Storage\&. " .ti -1c .RI "\fBOne\-time execution\fP" .br .RI "One-time execution\&. " .in -1c .SS "Data Structures" .in +1c .ti -1c .RI "union \fBglobus_thread_t\fP" .br .RI "Thread ID\&. " .ti -1c .RI "union \fBglobus_threadattr_t\fP" .br .RI "Thread attributes\&. " .ti -1c .RI "union \fBglobus_thread_key_t\fP" .br .RI "Thread-specific data key\&. " .in -1c .SS "Macros" .in +1c .ti -1c .RI "#define \fBGLOBUS_THREAD_CANCEL_DISABLE\fP 0" .br .RI "Disable thread cancellation value\&. " .ti -1c .RI "#define \fBGLOBUS_THREAD_CANCEL_ENABLE\fP 1" .br .RI "Enable thread cancellation value\&. " .ti -1c .RI "#define \fBGLOBUS_THREAD_MODULE\fP" .br .RI "Thread Module\&. " .in -1c .SS "Typedefs" .in +1c .ti -1c .RI "typedef void(* \fBglobus_thread_key_destructor_func_t\fP) (void *value)" .br .RI "Thread-specific data destructor\&. " .in -1c .SS "Functions" .in +1c .ti -1c .RI "int \fBglobus_thread_set_model\fP (const char *model)" .br .RI "Select threading model for an application\&. " .ti -1c .RI "int \fBglobus_thread_create\fP (\fBglobus_thread_t\fP *thread, \fBglobus_threadattr_t\fP *attr, globus_thread_func_t func, void *user_arg)" .br .RI "Create a new thread\&. " .ti -1c .RI "void \fBglobus_thread_yield\fP (void)" .br .RI "Yield execution to another thread\&. " .ti -1c .RI "void \fBglobus_thread_exit\fP (void *value)" .br .RI "Terminate the current thread\&. " .ti -1c .RI "int \fBglobus_thread_sigmask\fP (int how, const sigset_t *new_mask, sigset_t *old_mask)" .br .RI "Modify the current thread's signal mask\&. " .ti -1c .RI "int \fBglobus_thread_kill\fP (\fBglobus_thread_t\fP thread, int sig)" .br .RI "Send a signal to a thread\&. " .ti -1c .RI "\fBglobus_thread_t\fP \fBglobus_thread_self\fP (void)" .br .RI "Determine the current thread's ID\&. " .ti -1c .RI "\fBglobus_bool_t\fP \fBglobus_thread_equal\fP (\fBglobus_thread_t\fP thread1, \fBglobus_thread_t\fP thread2)" .br .RI "Check whether thread identifiers match\&. " .ti -1c .RI "\fBglobus_bool_t\fP \fBglobus_thread_preemptive_threads\fP (void)" .br .RI "Indicate whether the active thread model supports preemption\&. " .ti -1c .RI "\fBglobus_bool_t\fP \fBglobus_i_am_only_thread\fP (void)" .br .RI "Determine if threads are supported\&. " .ti -1c .RI "void * \fBglobus_thread_cancellable_func\fP (void *(*func)(void *), void *arg, void(*cleanup_func)(void *), void *cleanup_arg, \fBglobus_bool_t\fP execute_cleanup)" .br .RI "Execute a function with thread cleanup in case of cancellation\&. " .ti -1c .RI "int \fBglobus_thread_cancel\fP (\fBglobus_thread_t\fP thr)" .br .RI "Cancel a thread\&. " .ti -1c .RI "void \fBglobus_thread_testcancel\fP (void)" .br .RI "Thread cancellation point\&. " .ti -1c .RI "int \fBglobus_thread_setcancelstate\fP (int state, int *oldstate)" .br .RI "Set the thread's cancellable state\&. " .in -1c .SH "Detailed Description" .PP 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\&. .PP 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 \fBglobus_thread_set_model()\fP function prior to activating any Globus modules\&. .PP The Globus thread system provides primitives for mutual exclusion (\fBglobus_mutex_t\fP, \fBglobus_rmutex_t\fP, globus_rw_mutex_t), event synchronization (\fBglobus_cond_t\fP), one-time execution (globus_once_t), and threading (\fBglobus_thread_t\fP)\&. .PP In non-threaded operation, \fBglobus_cond_wait()\fP 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 \fBglobus_thread_create()\fP function will fail in that model\&. Other primitive operations will return success but not provide any thread exclusion as there is only one thread\&. .SH "Macro Definition Documentation" .PP .SS "#define GLOBUS_THREAD_CANCEL_DISABLE 0" .PP Disable thread cancellation value\&. .PP \fBSee also\fP .RS 4 \fBglobus_thread_setcancelstate()\fP .RE .PP .SS "#define GLOBUS_THREAD_CANCEL_ENABLE 1" .PP Enable thread cancellation value\&. .PP \fBSee also\fP .RS 4 \fBglobus_thread_setcancelstate()\fP .RE .PP .SH "Function Documentation" .PP .SS "\fBglobus_bool_t\fP globus_i_am_only_thread (void)" .PP Determine if threads are supported\&. The \fBglobus_i_am_only_thread()\fP function determines whether multiple threads may be running in this process\&. .PP \fBReturns\fP .RS 4 The \fBglobus_i_am_only_thread()\fP function returns GLOBUS_TRUE if the current thread model is the 'none' thread model; GLOBUS_FALSE otherwise\&. .RE .PP .SS "int globus_thread_cancel (\fBglobus_thread_t\fP thr)" .PP Cancel a thread\&. The \fBglobus_thread_cancel()\fP function cancels the thread with the identifier \fIthr\fP 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\&. .PP \fBParameters\fP .RS 4 \fIthr\fP The id of the thread to cancel .RE .PP \fBReturns\fP .RS 4 On success, the \fBglobus_thread_cancel()\fP function delivers the cancellation to the target thread and returns GLOBUS_SUCCESS\&. If an error occurs, \fBglobus_thread_cancel()\fP returns an implementation-specific non-zero error value\&. .RE .PP .SS "void * globus_thread_cancellable_func (void *(*)(void *) func, void * arg, void(*)(void *) cleanup_func, void * cleanup_arg, \fBglobus_bool_t\fP execute_cleanup)" .PP Execute a function with thread cleanup in case of cancellation\&. The \fBglobus_thread_cancellable_func()\fP function provides an interface to POSIX thread cancellation points that does not rely on preprocessor macros\&. It is roughly equivalent to .PP .nf pthread_cleanup_push(cleanup_func, cleanup_arg); (*func)(arg); pthread_cleanup_pop(execute_cleanup) .fi .PP .PP \fBParameters\fP .RS 4 \fIfunc\fP Pointer to a function which may be cancelled\&. .br \fIarg\fP Parameter to the \fIfunc\fP function\&. .br \fIcleanup_func\fP Pointer to a function to execute if thread cancellation occurs during \fIfunc\fP\&. .br \fIcleanup_arg\fP Parameter to the \fIcleanup_func\fP function\&. .br \fIexecute_cleanup\fP Flag indicating whether the function pointed to by \fIcleanup_func\fP should be executed after \fIfunc\fP completes even if it is not cancelled\&. .RE .PP \fBReturns\fP .RS 4 \fBglobus_thread_cancellable_func()\fP returns the value returned by \fIfunc\fP\&. .RE .PP .SS "int globus_thread_create (\fBglobus_thread_t\fP * thread, \fBglobus_threadattr_t\fP * attr, globus_thread_func_t func, void * user_arg)" .PP Create a new thread\&. The \fBglobus_thread_create()\fP function creates a new thread of execution in the current process to run the function pointed to by the \fIfunc\fP parameter passed the \fIuser_arg\fP 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 \fIthread\fP parameter if it is non-NULL\&. The caller may use this thread identifier to signal or cancel this thread\&. The \fIattr\fP 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 \fBGlobus Callback API \fP\&. .PP \fBParameters\fP .RS 4 \fIthread\fP Pointer to a variable to contain the new thread's identifier\&. .br \fIattr\fP Ignored .br \fIfunc\fP Pointer to a function to start in the new thread\&. .br \fIuser_arg\fP Argument to the new thread's function\&. .RE .PP \fBReturns\fP .RS 4 On success, \fBglobus_thread_create()\fP will start a new thread, invoking (*func)(user_arg), modify the value pointed to by the \fIthread\fP parameter to contain the new thread's identifier and return GLOBUS_SUCCESS\&. If an error occurs, then the value of \fIthread\fP is undefined and \fBglobus_thread_create()\fP returns an implementation-specific non-zero error value\&. .RE .PP .SS "\fBglobus_bool_t\fP globus_thread_equal (\fBglobus_thread_t\fP thread1, \fBglobus_thread_t\fP thread2)" .PP Check whether thread identifiers match\&. The \fBglobus_thread_equal()\fP function checks whether the thread identifiers passed as the \fIthread1\fP and \fIthread2\fP parameters refer to the same thread\&. If so, \fBglobus_thread_equal()\fP returns GLOBUS_TRUE; otherwise GLOBUS_FALSE\&. .PP \fBParameters\fP .RS 4 \fIthread1\fP Thread identifier to compare\&. .br \fIthread2\fP Thread identifier to compare\&. .RE .PP \fBReturn values\fP .RS 4 \fIGLOBUS_TRUE\fP thread1 and thread2 refer to the same thread\&. .br \fIGLOBUS_FALSE\fP thread1 and thread2 do not refer to the same thread\&. .RE .PP .SS "void globus_thread_exit (void * value)" .PP Terminate the current thread\&. The \fBglobus_thread_exit()\fP terminates the current thread with the value passed to it\&. This function does not return\&. .SS "int globus_thread_kill (\fBglobus_thread_t\fP thread, int sig)" .PP Send a signal to a thread\&. The \fBglobus_thread_kill()\fP function sends the signal specified by the \fIsig\fP number to the thread whose ID matches the \fIthread\fP 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\&. .PP \fBParameters\fP .RS 4 \fIthread\fP The thread identifier of the thread to signal\&. .br \fIsig\fP The signal to send to the thread\&. .RE .PP \fBReturns\fP .RS 4 On success, \fBglobus_thread_kill()\fP queues the signal for delivery to the specified thread and returns GLOBUS_SUCCESS\&. If an error occurs, \fBglobus_thread_kill()\fP returns an implementation-specific non-zero error value\&. .RE .PP .SS "\fBglobus_bool_t\fP globus_thread_preemptive_threads (void)" .PP Indicate whether the active thread model supports preemption\&. .PP \fBReturns\fP .RS 4 The \fBglobus_thread_preemptive_threads()\fP function returns GLOBUS_TRUE if the current thread model supports thread preemption; otherwise it returns GLOBUS_FALSE\&. .RE .PP .SS "\fBglobus_thread_t\fP globus_thread_self (void)" .PP Determine the current thread's ID\&. The \fBglobus_thread_self()\fP function returns the thread identifier of the current thread\&. This value is unique among all threads which are running at any given time\&. .PP \fBReturns\fP .RS 4 The \fBglobus_thread_self()\fP function returns the current thread's ID\&. .RE .PP .SS "int globus_thread_set_model (const char * model)" .PP Select threading model for an application\&. The \fBglobus_thread_set_model()\fP 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 \fBglobus_mutex_lock()\fP and \fBglobus_cond_wait()\fP) behave\&. This function overrides the value set by the GLOBUS_THREAD_MODEL environment variable\&. .PP The \fBglobus_thread_set_model()\fP function will fail if a Globus module has been activated already\&. .PP \fBParameters\fP .RS 4 \fImodel\fP 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\&. .RE .PP \fBReturns\fP .RS 4 On success, \fBglobus_thread_set_model()\fP sets the name of the thread model to use and returns GLOBUS_SUCCESS\&. If an error occurs, then \fBglobus_thread_set_model()\fP returns GLOBUS_FAILURE\&. .RE .PP .SS "int globus_thread_setcancelstate (int state, int * oldstate)" .PP Set the thread's cancellable state\&. The \fBglobus_thread_setcancelstate()\fP function sets the current cancellation state to either GLOBUS_THREAD_CANCEL_DISABLE or GLOBUS_THREAD_CANCEL_ENABLE, do control whether \fBglobus_thread_cancel()\fP is able to cancel this thread\&. .PP \fBParameters\fP .RS 4 \fIstate\fP 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\&. .br \fIoldstate\fP 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\&. .RE .PP \fBReturns\fP .RS 4 On success, the \fBglobus_thread_setcancelstate()\fP 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, \fBglobus_thread_setcancelstate()\fP returns an implementation-specific non-zero error value\&. .RE .PP .SS "int globus_thread_sigmask (int how, const sigset_t * new_mask, sigset_t * old_mask)" .PP Modify the current thread's signal mask\&. The \fBglobus_thread_sigmask()\fP function modifies the current thread's signal mask and returns the old value of the signal mask in the value pointed to by the \fIold_mask\fP parameter\&. The \fIhow\fP parameter can be one of SIG_BLOCK, SIG_UNBLOCK, or SIG_SETMASK to control how the signal mask is modified\&. .PP \fBParameters\fP .RS 4 \fIhow\fP Flag indicating how to interpret \fInew_mask\fP if it is non-NULL\&. If \fIhow\fP is SIG_BLOCK, then all signals in \fInew_mask\fP are blocked, as well as any which were previously blocked\&. If \fIhow\fP is SIG_UNBLOCK, then all signals in which were previously blocked in \fInew_mask\fP are unblocked\&. If \fIhow\fP is SIG_SETMASK, then the old signal mask is replaced with the value of \fInew_mask\fP\&. .br \fInew_mask\fP Set of signals to block or unblock, based on the \fIhow\fP parameter\&. .br \fIold_mask\fP A pointer to be set to the old signal mask associated with the current thread\&. .RE .PP \fBReturns\fP .RS 4 On success, \fBglobus_thread_sigmask()\fP modifies the signal mask, modifies the value pointed to by \fIold_mask\fP with the signal mask prior to this function's execution and returns GLOBUS_SUCCESS\&. If an error occurs, \fBglobus_thread_sigmask()\fP returns an implementation-specific non-zero error value\&. .RE .PP .SS "void globus_thread_testcancel (void)" .PP Thread cancellation point\&. The \fBglobus_thread_testcancel()\fP function acts as a cancellation point for the current thread\&. If a thread has called \fBglobus_thread_cancel()\fP 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\&. .SS "void globus_thread_yield (void)" .PP Yield execution to another thread\&. The \fBglobus_thread_yield()\fP 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\&. .SH "Author" .PP Generated automatically by Doxygen for globus_common from the source code\&.