path: root/manual/threads.texi

@node Threads
@c @node Threads, Internal Probes, Debugging Support, Top
@c %MENU% Functions, constants, and data types for working with threads
@chapter Threads
@cindex threads

This chapter describes functions used for managing threads.
@Theglibc{} provides two threading implementations: ISO C threads and
POSIX threads.

@menu
* ISO C Threads::	Threads based on the ISO C specification.
* POSIX Threads::	Threads based on the POSIX specification.
@end menu


@node ISO C Threads
@section ISO C Threads
@cindex ISO C threads
@cindex C threads
@pindex threads.h

This section describes the @glibcadj{} ISO C threads implementation.
To have a deeper understanding of this API, it is strongly recommended
to read ISO/IEC 9899:2011, section 7.26, in which ISO C threads were
originally specified.  All types and function prototypes are declared
in the header file @file{threads.h}.

@menu
* ISO C Threads Return Values:: Symbolic constants that represent a
				function's return value.
* ISO C Thread Management::	Support for basic threading.
* Call Once::			Single-call functions and macros.
* ISO C Mutexes::		A low-level mechanism for mutual exclusion.
* ISO C Condition Variables::	High-level objects for thread synchronization.
* ISO C Thread-local Storage::	Functions to support thread-local storage.
@end menu


@node ISO C Threads Return Values
@subsection Return Values

The ISO C thread specification provides the following enumeration
constants for return values from functions in the API:

@vtable @code
@item thrd_timedout
@standards{C11, threads.h}
A specified time was reached without acquiring the requested resource,
usually a mutex or condition variable.

@item thrd_success
@standards{C11, threads.h}
The requested operation succeeded.

@item thrd_busy
@standards{C11, threads.h}
The requested operation failed because a requested resource is already
in use.

@item thrd_error
@standards{C11, threads.h}
The requested operation failed.

@item thrd_nomem
@standards{C11, threads.h}
The requested operation failed because it was unable to allocate
enough memory.
@end vtable


@node ISO C Thread Management
@subsection Creation and Control
@cindex thread creation
@cindex thread control
@cindex thread management

@Theglibc{} 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:

@deftp {Data Type} thrd_t
@standards{C11, threads.h}
A unique object that identifies a thread.
@end deftp

@deftp {Data Type} thrd_start_t
@standards{C11, threads.h}
This data type is an @code{int (*) (void *)} typedef that is passed to
@code{thrd_create} when creating a new thread.  It should point to the
first function that thread will run.
@end deftp

The following functions are used for working with threads:

@deftypefun int thrd_create (thrd_t *@var{thr}, thrd_start_t @var{func}, void *@var{arg})
@standards{C11, threads.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@code{thrd_create} creates a new thread that will execute the function
@var{func}.  The object pointed to by @var{arg} will be used as the
argument to @var{func}.  If successful, @var{thr} is set to the new
thread identifier.

This function may return @code{thrd_success}, @code{thrd_nomem}, or
@code{thrd_error}.
@end deftypefun

@deftypefun thrd_t thrd_current (void)
@standards{C11, threads.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function returns the identifier of the calling thread.
@end deftypefun

@deftypefun int thrd_equal (thrd_t @var{lhs}, thrd_t @var{rhs})
@standards{C11, threads.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@code{thrd_equal} checks whether @var{lhs} and @var{rhs} refer to the
same thread.  If @var{lhs} and @var{rhs} are different threads, this
function returns @math{0}; otherwise, the return value is non-zero.
@end deftypefun

@deftypefun int thrd_sleep (const struct timespec *@var{time_point}, struct timespec *@var{remaining})
@standards{C11, threads.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@code{thrd_sleep} blocks the execution of the current thread for at
least until the elapsed time pointed to by @var{time_point} has been
reached.  This function does not take an absolute time, but a duration
that the thread is required to be blocked.  @xref{Time Basics}, and
@ref{Elapsed Time}.

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

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

@deftypefun void thrd_yield (void)
@standards{C11, threads.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@code{thrd_yield} provides a hint to the implementation to reschedule
the execution of the current thread, allowing other threads to run.
@end deftypefun

@deftypefun {_Noreturn void} thrd_exit (int @var{res})
@standards{C11, threads.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@code{thrd_exit} terminates execution of the calling thread and sets
its result code to @var{res}.

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

@deftypefun int thrd_detach (thrd_t @var{thr})
@standards{C11, threads.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@code{thrd_detach} detaches the thread identified by @code{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 @var{thr} signal.

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

This function returns either @code{thrd_success} or @code{thrd_error}.
@end deftypefun

@deftypefun int thrd_join (thrd_t @var{thr}, int *@var{res})
@standards{C11, threads.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@code{thrd_join} blocks the current thread until the thread identified
by @code{thr} finishes execution.  If @code{res} is not NULL, the
result code of the thread is put into the location pointed to by
@var{res}.  The termination of the thread @dfn{synchronizes-with} the
completion of this function, meaning both threads have arrived at a
common point in their execution.

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

This function returns either @code{thrd_success} or @code{thrd_error}.
@end deftypefun


@node Call Once
@subsection Call Once
@cindex call once
@cindex single-call functions

In order to guarantee single access to a function, @theglibc{}
implements a @dfn{call once function} to ensure a function is only
called once in the presence of multiple, potentially calling threads.

@deftp {Data Type} once_flag
@standards{C11, threads.h}
A complete object type capable of holding a flag used by @code{call_once}.
@end deftp

@defvr Macro ONCE_FLAG_INIT
@standards{C11, threads.h}
This value is used to initialize an object of type @code{once_flag}.
@end defvr

@deftypefun void call_once (once_flag *@var{flag}, void (*@var{func}) (void))
@standards{C11, threads.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@code{call_once} calls function @var{func} exactly once, even if
invoked from several threads.  The completion of the function
@var{func} synchronizes-with all previous or subsequent calls to
@code{call_once} with the same @code{flag} variable.
@end deftypefun


@node ISO C Mutexes
@subsection Mutexes
@cindex mutex
@cindex mutual exclusion

To have better control of resources and how threads access them,
@theglibc{} implements a @dfn{mutex} object, which can help avoid race
conditions and other concurrency issues.  The term ``mutex'' refers to
mutual exclusion.

The fundamental data type for a mutex is the @code{mtx_t}:

@deftp {Data Type} mtx_t
@standards{C11, threads.h}
The @code{mtx_t} data type uniquely identifies a mutex object.
@end deftp

The ISO C standard defines several types of mutexes.  They are
represented by the following symbolic constants:

@vtable @code
@item mt