--- name: "globus_thread_yield" section: "3" platform: "linux" package: "libglobus-common-doc" version: "18.14-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/globus_thread" --- # globus\_thread\_yield(3) Threading - Portable Thread Abstraction. Part of [globus\_thread(3)](/globus_thread/3.md). ## 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.