Globus Common: Threads & Synchronization Function Reference

Overview


Nexus threads are modeled after a subset of POSIX threads (IEEE standard P1003.4a). This section describes the functions provided by Nexus for basic thread operations such as creation, destruction, mutual exclusion, and synchronization.

Activation and Deactivation


Globus Threads are a part of the Globus common library. Before any Globus Threads functions are called, the following function must be called:

globus_module_activate(GLOBUS_COMMON_MODULE);

This function returns GLOBUS_SUCCESS if Globus common was successfully initialized, and you are therefore allowed to subsequently call Globus common functions. Otherwise, and error code is returned, and Globus common functions should not be subsequently called. This function may be called multiple times.

To deactivate the Globus common library, the following function must be called:

globus_module_deactivate(GLOBUS_COMMON_MODULE);

This function should be called once for each time the Globus common library was activated.

Functions

 

int
globus_thread_create(
    globus_thread_t *thread,
    globus_thread_attr_t *attr,
    globus_thread_func_t func,
    void *user_arg)

typedef void *
(*globus_thread_func_t)(void *user_arg);

Create a new thread in the current context which invokes the supplied function func with one argument user_arg. The thread ID for the newly created thread is placed in thread. Return zero if the thread is successfully created, or non-zero otherwise.

The attr argument for specification of attributes for the thread. However, this is not yet implemented.

Note: There are no equivalents to pthread_detach() and pthread_join() in Nexus. All Nexus threads are automatically detached when they are created.

void
globus_thread_exit(
    void *status)

Terminate the calling thread. Returning from the user thread function will implicitly terminate the thread.

The status argument is currently not used.

void
globus_thread_yield()

Yield the processor to another thread.

globus_thread_t
globus_thread_self()

Return the thread ID of the calling thread.

int
globus_thread_equal(
    globus_thread_t t1,
    globus_thread_t t2)

Compare the two thread IDs, t1 and t2. If they are the same then this returns non-zero, otherwise it returns zero.

globus_thread_once_t once_control = GLOBUS_THREAD_ONCE_INIT;

int
globus_thread_once(
    globus_thread_once_t *once_control,
    void (*init_routine)() )

The first call to globus_thread_once() by any thread in a context, with a given once_control, will call the init_routine() with no arguments. Subsequent calls of globus_thread_once() will not call the init_routine(). On return of globus_thread_once() it is guaranteed that init_routine() has completed. The once_control parameter is used to determine whether the associated initialization routine has been called.

This returns 0 upon successful completion, otherwise -1.

typedef void
(*globus_thread_key_destructor_func_t)(void *value);

int
globus_thread_key_create(
     globus_thread_key_t *key,
     globus_thread_key_destructor_func_t func)

Create a thread specific data key that is visible to all threads in the context, and place that key in the key argument. Although the same key value may be used by different threads, the values bound to the key by globus_thread_setspecific() are maintained on a per-thread basis.

The value associated with a new key is NULL in all active threads, and will be initialized to NULL in all threads that are subsequently created.

If func is not NULL, then upon termination of the thread if the value for this key is not NULL the function pointed to by func is called with the current value for the key as its argument.

This function returns zero upon successful completion, or non-zero otherwise. A -1 return indicates that the key name space is exhaused.

int
globus_thread_setspecific(
    globus_thread_key_t key,
    void *value)

Set the value associated with the thread specific data key to value. Different threads may bind different values to the same key.

This function returns zero upon successful completion, or non-zero otherwise.

void *
globus_thread_getspecific(
     globus_thread_key_t key)

Return the thread specific data value associated with key.

int
globus_mutex_init(
    globus_mutex_t *mutex,
    globus_mutexattr_t *attr)

Initialize the mutual exclusion lock, mutex. The attributes for the mutex are specified by attr. Default attributes will be used if attr is NULL.

The result of calling globus_mutex_lock() or globus_mutex_unlock() on a mutex that has not been initialized is undefined.

This function returns zero upon successful completion, or non-zero otherwise.

int
globus_mutex_destroy(
    globus_mutex_t *mutex)

Destroy the mutex that was initialized with globus_mutex_init(). The result of calling globus_mutex_lock() or globus_mutex_unlock() on a mutex that has been destroyed is undefined.

This function returns zero upon successful completion, or non-zero otherwise.

int
globus_mutex_lock(
     globus_mutex_t *mutex)

Block until the mutual exclusion lock, mutex, is acquired. This may or may not be implemented as a spin lock (i.e., busy wait).

This function returns zero upon successful completion, or non-zero otherwise.

int
globus_mutex_unlock(
    globus_mutex_t *mutex)

Unlock the mutual exclusion lock, mutex, enabling another thread to acquire the mutex. Fairness in locking is not guaranteed; that is, a thread is not guaranteed to acquire a lock if other threads are also attempting to acquire the same lock.

This function returns zero upon successful completion, or non-zero otherwise.

int
globus_mutex_trylock(
    globus_mutex_t * mutex)

This function checks to see if it can aquire the lock. It it is busy, it will return immediately, rather than waiting to aquire it like globus_mutex_lock.

Mutex is the monitor identifier.

This function returns zero upon successful completion, or non-zero otherwise.

int
globus_cond_init(
    globus_cond_t *cond,
    globus_condattr_t *attr)

Initialize the condition variable, cond. The attributes for the condition are specified by attr. Default attributes will be used if attr is NULL.

The result of calling any other globus_cond_*() function on a condition that has not been initialized is undefined.

This function returns zero upon successful completion, or non-zero otherwise.

int
globus_cond_destroy(
    globus_cond_t *cond)

Destroy the specified condition. The result of calling any other globus_cond_*() function on a condition that has been destroyed is undefined.

This function returns zero upon successful completion, or non-zero otherwise.

int
globus_cond_wait(
    globus_cond_t *cond,
    globus_mutex_t *mutex)

Atomically release mutex and wait on cond. When the function returns, mutex has been reacquired.

If the thread executing the function has not acquired mutex, the result is undefined.

This function returns zero upon successful completion, or non-zero otherwise.

int
globus_cond_signal(
   globus_cond_t *cond)

Signal the specified condition, waking up one thread that is suspended on this condition. If no threads are suspended on this condition, this call will have no effect.

This function returns zero upon successful completion, or non-zero otherwise.

int
globus_cond_broadcast(
    globus_cond_t *cond)

Unsuspend all threads suspended on the specified condition.

This function returns zero upon successful completion, or non-zero otherwise.