.TH "globus_thread" 3 "Tue Jul 5 2022" "Version 18.13" "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   (&globus_i_thread_module)"
.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\&.