# FindThreads

Finds and determines the thread library of the system for multithreading support:

    find_package(Threads [...])

Multithreading enables concurrent execution within a single program, typically by creating multiple threads of execution. Most commonly, this is done using libraries such as POSIX Threads (`pthreads`) on Unix-like systems or Windows threads on Windows.

This module abstracts the platform-specific differences and detects how to enable thread support - whether it requires linking to a specific library, adding compiler flags (like `-pthread`), or both. On some platforms, threading is also implicitly available in default libraries without the need to use additional flags or libraries.

This module is suitable for use in both C and C++ projects (and occasionally other compiled languages) that rely on system-level threading APIs.

Using this module ensures that project builds correctly across different platforms by handling the detection and setup of thread support in a portable way.

## C and C++ Language Standards

The C11 standard introduced a minimal cross-platform thread API via `<threads.h>` header file, and C++11 added `<thread>` header to the standard library, offering high-level multithreading support. These standard headers allow writing portable threaded code at the language level, without directly using platform-specific APIs like `pthreads` or Windows threads.

However, even with standard C11 or C++11 threads support available, there may still be a need for platform-specific compiler or linker flags (e.g., `-pthread` on Unix-like systems) for some applications. This is where FindThreads remains relevant - it ensures these flags and any required libraries are correctly set up, even if not explicitly using system APIs.

In short:

- Use `<thread>` (C++11 and later) or `<threads.h>` (C11) in source code for portability and simpler syntax.

- Use `find_package(Threads)` in CMake project when application needs the traditional threading support and to ensure code compiles and links correctly across different platforms.

## Imported Targets

This module provides the following Imported Targets:

`Threads::Threads`

  Added in version 3.1.

  Target encapsulating the usage requirements to enable threading through flags or a threading library, if found. This target is available if threads are detected as supported.

## Result Variables

This module defines the following variables:

`Threads_FOUND`

  Boolean indicating whether Threads is supported, either through a separate library or a standard library.

`CMAKE_THREAD_LIBS_INIT`

  The thread library to use. This may be empty if the thread functions are provided by the system libraries and no special flags are needed to use them.

`CMAKE_USE_WIN32_THREADS_INIT`

  If the found thread library is the win32 one.

`CMAKE_USE_PTHREADS_INIT`

  If the found thread library is pthread compatible.

`CMAKE_HP_PTHREADS_INIT`

  If the found thread library is the HP thread library.

## Variables Affecting Behavior

This module accepts the following variables before calling `find_package(Threads)`:

`THREADS_PREFER_PTHREAD_FLAG`

  Added in version 3.1.

  If the use of the `-pthread` compiler and linker flag is preferred then the caller can set this variable to boolean true. The compiler flag can only be used with the imported target. Use of both the imported target as well as this switch is highly recommended for new code.

  This variable has no effect if the system libraries provide the thread functions, i.e. when `CMAKE_THREAD_LIBS_INIT` will be empty.

## Examples

Finding Threads and linking the imported target to a project target:

    set(THREADS_PREFER_PTHREAD_FLAG TRUE)
    find_package(Threads)
    target_link_libraries(example PRIVATE Threads::Threads)