Threading
Collaboration diagram for Threading:

Modules

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

Data Structures

union  globus_thread_t
 
union  globus_threadattr_t
 
union  globus_thread_key_t
 

Macros

#define GLOBUS_THREAD_CANCEL_DISABLE   0
 
#define GLOBUS_THREAD_CANCEL_ENABLE   1
 
#define GLOBUS_THREAD_MODULE   (&globus_i_thread_module)
 

Typedefs

typedef void(* globus_thread_key_destructor_func_t )(void *value)
 

Functions

int globus_thread_set_model (const char *model)
 
int globus_thread_create (globus_thread_t *thread, globus_threadattr_t *attr, globus_thread_func_t func, void *user_arg)
 
void globus_thread_yield (void)
 
void globus_thread_exit (void *value)
 
int globus_thread_sigmask (int how, const sigset_t *new_mask, sigset_t *old_mask)
 
int globus_thread_kill (globus_thread_t thread, int sig)
 
globus_thread_t globus_thread_self (void)
 
globus_bool_t globus_thread_equal (globus_thread_t thread1, globus_thread_t thread2)
 
globus_bool_t globus_thread_preemptive_threads (void)
 
globus_bool_t globus_i_am_only_thread (void)
 
void * globus_thread_cancellable_func (void *(*func)(void *), void *arg, void(*cleanup_func)(void *), void *cleanup_arg, globus_bool_t execute_cleanup)
 
int globus_thread_cancel (globus_thread_t thr)
 
void globus_thread_testcancel (void)
 
int globus_thread_setcancelstate (int state, int *oldstate)
 

Detailed Description

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()
#define GLOBUS_THREAD_MODULE   (&globus_i_thread_module)

Thread Module.

Typedef Documentation

typedef void(* globus_thread_key_destructor_func_t)(void *value)

Thread-specific data destructor.

Function Documentation

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
modelThe 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_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 @a func
parameter passed the @a 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 @a thread
parameter if it is non-NULL. The caller may use this thread identifier
to signal or cancel this thread. The @a attr paramter 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
@link globus_callback Globus Callback API @endlink.
Parameters
threadPointer to a variable to contain the new thread's identifier.
attrIgnored
funcPointer to a function to start in the new thread.
user_argArgument 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.
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.

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_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 @a old_mask parameter. The @a how parameter can be
one of SIG_BLOCK, SIG_UNBLOCK, or SIG_SETMASK to control how the
signal mask is modified.
Parameters
howFlag 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_maskSet of signals to block or unblock, based on the how parameter.
old_maskA 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.
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
@a sig number to the thread whose ID matches the @a 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
threadThe thread identifier of the thread to signal.
sigThe 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_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.

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 @a thread1 and @a thread2 parameters refer to the same
thread. If so, globus_thread_equal() returns GLOBUS_TRUE; otherwise
GLOBUS_FALSE.
Parameters
thread1Thread identifier to compare.
thread2Thread identifier to compare.
globus_bool_t globus_thread_preemptive_threads ( void  )

Indicate whether the active thread model supports preemption.

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

globus_bool_t globus_i_am_only_thread ( void  )

Determine if threads are supported.

The globus_i_am_only_thread() function returns GLOBUS_TRUE if the current thread model is the "none" thread model; GLOBUS_FALSE otherwise. If running with the "none" thread model, there will only be one Globus thread available and the globus_thread_create() function will always fail.

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
funcPointer to a function which may be cancelled.
argParameter to the func function.
cleanup_funcPointer to a function to execute if thread cancellation occurs during func.
cleanup_argParameter to the cleanup_func function.
execute_cleanupFlag 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_cancel ( globus_thread_t  thr)

Cancel a thread.

The globus_thread_cancel() function cancels the thread with the
identifier @a 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
thrThe 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_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.

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
stateThe 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.
oldstateA 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.

about globus | globus toolkit | dev.globus

Comments? webmaster@globus.org