---

35.1.2 Creation and Control

The GNU C Library implements a set of functions that allow the user to easily create and use threads. Additional functionality is provided to control the behavior of threads.

The following data types are defined for managing threads:

Data Type: thrd_t ¶

A unique object that identifies a thread.

Data Type: thrd_start_t ¶

This data type is an int (*) (void *) typedef that is passed to thrd_create when creating a new thread. It should point to the first function that thread will run.

The following functions are used for working with threads:

Function: int thrd_create (thrd_t *thr, thrd_start_t func, void *arg) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

thrd_create creates a new thread that will execute the function func. The object pointed to by arg will be used as the argument to func. If successful, thr is set to the new thread identifier.

This function may return thrd_success, thrd_nomem, or thrd_error.

Function: thrd_t thrd_current (void) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function returns the identifier of the calling thread.

Function: int thrd_equal (thrd_t lhs, thrd_t rhs) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

thrd_equal checks whether lhs and rhs refer to the same thread. If lhs and rhs are different threads, this function returns 0; otherwise, the return value is non-zero.

Function: int thrd_sleep (const struct timespec *time_point, struct timespec *remaining) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

thrd_sleep blocks the execution of the current thread for at least until the elapsed time pointed to by time_point has been reached. This function does not take an absolute time, but a duration that the thread is required to be blocked. See Time Basics, and Elapsed Time.

The thread may wake early if a signal that is not ignored is received. In such a case, if remaining is not NULL, the remaining time duration is stored in the object pointed to by remaining.

thrd_sleep returns 0 if it blocked for at least the amount of time in time_point, -1 if it was interrupted by a signal, or a negative number on failure.

Function: void thrd_yield (void) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

thrd_yield provides a hint to the implementation to reschedule the execution of the current thread, allowing other threads to run.

Function: _Noreturn void thrd_exit (int res) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

thrd_exit terminates execution of the calling thread and sets its result code to res.

If this function is called from a single-threaded process, the call is equivalent to calling exit with EXIT_SUCCESS (see Normal Termination). Also note that returning from a function that started a thread is equivalent to calling thrd_exit.

Function: int thrd_detach (thrd_t thr) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

thrd_detach detaches the thread identified by thr from the current control thread. The resources held by the detached thread will be freed automatically once the thread exits. The parent thread will never be notified by any thr signal.

Calling thrd_detach on a thread that was previously detached or joined by another thread results in undefined behavior.

This function returns either thrd_success or thrd_error.

Function: int thrd_join (thrd_t thr, int *res) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

thrd_join blocks the current thread until the thread identified by thr finishes execution. If res is not NULL, the result code of the thread is put into the location pointed to by res. The termination of the thread synchronizes-with the completion of this function, meaning both threads have arrived at a common point in their execution.

Calling thrd_join on a thread that was previously detached or joined by another thread results in undefined behavior.

This function returns either thrd_success or thrd_error.