NAME

threads.h — ISO C threads

SYNOPSIS

#include <threads.h>

DESCRIPTION

^[CX] The functionality described on this reference page is aligned with the ISO C standard. Any conflict between the requirements described here and the ISO C standard is unintentional. This volume of POSIX.1-2024 defers to the ISO C standard.

Implementations shall not define the macro __STDC_NO_THREADS__, except for profile implementations that define _POSIX_SUBPROFILE (see 2.1.5.1 Subprofiling Considerations) in <unistd.h>, which may define __STDC_NO_THREADS__ and, if they do so, need not provide this header nor support any of its facilities.

The <threads.h> header shall define the following macros:

thread_local

Expands to _Thread_local.

ONCE_FLAG_INIT

Expands to a value that can be used to initialize an object of type once_flag.

TSS_DTOR_ITERATIONS

Expands to an integer constant expression representing the maximum number of times that destructors will be called when a thread terminates and shall be suitable for use in #if preprocessing directives.

^[CX] If {PTHREAD_DESTRUCTOR_ITERATIONS} is defined in <limits.h>, the value of TSS_DTOR_ITERATIONS shall be equal to {PTHREAD_DESTRUCTOR_ITERATIONS}; otherwise, the value of TSS_DTOR_ITERATIONS shall be greater than or equal to the value of {_POSIX_THREAD_DESTRUCTOR_ITERATIONS} and shall be less than or equal to the maximum positive value that can be returned by a call to sysconf(_SC_THREAD_DESTRUCTOR_ITERATIONS) in any process.

The <threads.h> header shall define the types cnd_t, mtx_t, once_flag, thrd_t, and tss_t as complete object types, the type thrd_start_t as the function pointer type int (*)(void*), and the type tss_dtor_t as the function pointer type void (*)(void*). ^[CX] The type thrd_t shall be defined to be the same type that pthread_t is defined to be in <pthread.h>.

The <threads.h> header shall define the enumeration constants mtx_plain, mtx_recursive, mtx_timed, thrd_busy, thrd_error, thrd_nomem, thrd_success and thrd_timedout.

The following shall be declared as functions and may also be defined as macros. Function prototypes shall be provided.

void            call_once(once_flag *, void (*)(void));
int             cnd_broadcast(cnd_t *);
void            cnd_destroy(cnd_t *);
int             cnd_init(cnd_t *);
int             cnd_signal(cnd_t *);
int             cnd_timedwait(cnd_t * restrict, mtx_t * restrict,
                    const struct timespec * restrict);
int             cnd_wait(cnd_t *, mtx_t *);
void            mtx_destroy(mtx_t *);
int             mtx_init(mtx_t *, int);
int             mtx_lock(mtx_t *);
int             mtx_timedlock(mtx_t * restrict,
                    const struct timespec * restrict);
int             mtx_trylock(mtx_t *);
int             mtx_unlock(mtx_t *);
int             thrd_create(thrd_t *, thrd_start_t, void *);
thrd_t          thrd_current(void);
int             thrd_detach(thrd_t);
int             thrd_equal(thrd_t, thrd_t);
_Noreturn void  thrd_exit(int);
int             thrd_join(thrd_t, int *);
int             thrd_sleep(const struct timespec *, struct timespec *);
void            thrd_yield(void);
int             tss_create(tss_t *, tss_dtor_t);
void            tss_delete(tss_t);
void           *tss_get(tss_t);
int             tss_set(tss_t, void *);

Inclusion of the <threads.h> header shall make symbols defined in the header <time.h> visible.

APPLICATION USAGE

The <threads.h> header is optional in the ISO C standard but is mandated by POSIX.1-2024. Note however that subprofiles can choose to make this header optional (see 2.1.5.1 Subprofiling Considerations), and therefore application portability to subprofile implementations would benefit from checking whether __STDC_NO_THREADS__ is defined before inclusion of <threads.h>.

The features provided by <threads.h> are not as extensive as those provided by <pthread.h>. It is present on POSIX.1 implementations in order to facilitate porting of ISO C programs that use it. It is recommended that applications intended for use on POSIX.1 implementations use <pthread.h> rather than <threads.h> even if none of the additional features are needed initially, to save the need to convert should the need to use them arise later in the application's lifecycle.

RATIONALE

Although the <threads.h> header is optional in the ISO C standard, it is mandated by POSIX.1-2024 because <pthread.h> is mandatory and the interfaces in <threads.h> can easily be implemented as a thin wrapper for interfaces in <pthread.h>.

The type thrd_t is required to be defined as the same type that pthread_t is defined to be in <pthread.h> because thrd_current() and pthread_self() need to return the same thread ID when called from the initial thread. However, these types are not fully interchangeable (that is, it is not always possible to pass a thread ID obtained as a thrd_t to a function that takes a pthread_t, and vice versa) because threads created using thrd_create() have a different exit status than pthreads threads, which is reflected in differences between the prototypes for thrd_create() and pthread_create(), thrd_exit() and pthread_exit(), and thrd_join() and pthread_join(); also, thrd_join() has no way to indicate that a thread was cancelled.

The standard developers considered making it implementation-defined whether the types cnd_t, mtx_t and tss_t are interchangeable with the corresponding types pthread_cond_t, pthread_mutex_t and pthread_key_t defined in <pthread.h> (that is, whether any function that can be called with a valid cnd_t can also be called with a valid pthread_cond_t, and vice versa, and likewise for the other types). However, this would have meant extending mtx_lock() to provide a way for it to indicate that the owner of a mutex has terminated (equivalent to [EOWNERDEAD]). It was felt that such an extension would be invention. Although there was no similar concern for cnd_t and tss_t, they were treated the same way as mtx_t for consistency. See also the RATIONALE for mtx_lock() concerning the inability of mtx_t to contain information about whether or not a mutex supports timeout if it is the same type as pthread_mutex_t.

FUTURE DIRECTIONS

None.

SEE ALSO

<limits.h>, <pthread.h>, <time.h>

XSH 2.9 Threads, call_once, cnd_broadcast, cnd_destroy, cnd_timedwait, mtx_destroy, mtx_lock, sysconf, thrd_create, thrd_current, thrd_detach, thrd_equal, thrd_exit, thrd_join, thrd_sleep, thrd_yield, tss_create, tss_delete, tss_get

CHANGE HISTORY

First released in Issue 8. Included for alignment with the ISO/IEC 9899:2018 standard.