# std::thread::thread

From cppreference.com
< cpp‎ | thread‎ | thread

thread() noexcept; | (1) | (since C++11)
thread( thread&& other ) noexcept; | (2) | (since C++11)
template< class F, class... Args > explicit thread( F&& f, Args&&... args ); | (3) | (since C++11)
thread( const thread& ) = delete; | (4) | (since C++11)

Constructs a new `std::thread` object.

1) Creates a new `std::thread` object which does not represent a thread.
2) Move constructor. Constructs the `std::thread` object to represent the thread of execution that was represented by other. After this call other no longer represents a thread of execution.
3) Creates a new `std::thread` object and associates it with a thread of execution. The new thread of execution starts executing:

`INVOKE` ( `decay-copy` ( std::forward <F>(f)), `` `decay-copy` ( std::forward <Args>(args))...) | (until C++23)
std::invoke (auto( std::forward <F>(f)), auto( std::forward <Args>(args))...) | (since C++23)

The calls of `decay-copy` are evaluated(until C++23)The values produced by auto are materialized (since C++23) in the current thread, so that any exceptions thrown during evaluation and copying/moving of the arguments are thrown in the current thread, without starting the new thread.
This overload participates in overload resolution only if std::decay <F>::type(until C++20) std::remove_cvref_t <F>(since C++20) is not the same type as `std::thread`.

If any of the following conditions is satisfied, the program is ill-formed:

- `F` is not MoveConstructible.
- Any type in `Args` is not MoveConstructible.
- `INVOKE` ( `decay-copy` ( std::forward <F>(f)),
  `` `decay-copy` ( std::forward <Args>(args))...) is not a valid expression.

(until C++20)

If any of the following is false, the program is ill-formed:

- std::is_constructible_v < std::decay_t <F>, F>
- ( std::is_constructible_v < std::decay_t <Args>, Args> && ...)
- std::is_invocable_v < std::decay_t <F>, std::decay_t <Args>...>

(since C++20)

The completion of the invocation of the constructor synchronizes with the beginning of the invocation of the copy of f on the new thread of execution.
4) The copy constructor is deleted; threads are not copyable. No two `std::thread` objects may represent the same thread of execution.

### Parameters

other | - | another thread object to construct this thread object with
f | - | Callable object to execute in the new thread
args | - | arguments to pass to the new function

### Postconditions

1) get_id() equal to std::thread::id () (i.e. joinable() is false).
2) other.get_id() equal to std::thread::id() and get_id() returns the value of other.get_id() prior to the start of construction.
3) get_id() not equal to std::thread::id() (i.e. joinable() is true).

### Exceptions

3) std::system_error if the thread could not be started. The exception may represent the error condition `std::errc::resource_unavailable_try_again` or another implementation-specific error condition.

### Notes

The arguments to the thread function are moved or copied by value. If a reference argument needs to be passed to the thread function, it has to be wrapped (e.g., with std::ref or std::cref).

Any return value from the function is ignored. If the function throws an exception, std::terminate is called. In order to pass return values or exceptions back to the calling thread, std::promise or std::async may be used.

### Example

Run this code

    #include <chrono>
    #include <iostream>
    #include <thread>
    #include <utility>

    void f1(int n)
    {
        for (int i = 0; i < 5; ++i)
        {
            std::cout << "Thread 1 executing\n";
            ++n;
            std::this_thread::sleep_for(std::chrono::milliseconds(10));
        }
    }

    void f2(int& n)
    {
        for (int i = 0; i < 5; ++i)
        {
            std::cout << "Thread 2 executing\n";
            ++n;
            std::this_thread::sleep_for(std::chrono::milliseconds(10));
        }
    }

    class foo
    {
    public:
        void bar()
        {
            for (int i = 0; i < 5; ++i)
            {
                std::cout << "Thread 3 executing\n";
                ++n;
                std::this_thread::sleep_for(std::chrono::milliseconds(10));
            }
        }
        int n = 0;
    };

    class baz
    {
    public:
        void operator()()
        {
            for (int i = 0; i < 5; ++i)
            {
                std::cout << "Thread 4 executing\n";
                ++n;
                std::this_thread::sleep_for(std::chrono::milliseconds(10));
            }
        }
        int n = 0;
    };

    int main()
    {
        int n = 0;
        foo f;
        baz b;
        std::thread t1; // t1 is not a thread
        std::thread t2(f1, n + 1); // pass by value
        std::thread t3(f2, std::ref(n)); // pass by reference
        std::thread t4(std::move(t3)); // t4 is now running f2(). t3 is no longer a thread
        std::thread t5(&foo::bar, &f); // t5 runs foo::bar() on object f
        std::thread t6(b); // t6 runs baz::operator() on a copy of object b
        t2.join();
        t4.join();
        t5.join();
        t6.join();
        std::cout << "Final value of n is " << n << '\n';
        std::cout << "Final value of f.n (foo::n) is " << f.n << '\n';
        std::cout << "Final value of b.n (baz::n) is " << b.n << '\n';
    }

Possible output:

    Thread 1 executing
    Thread 2 executing
    Thread 3 executing
    Thread 4 executing
    Thread 3 executing
    Thread 1 executing
    Thread 2 executing
    Thread 4 executing
    Thread 2 executing
    Thread 3 executing
    Thread 1 executing
    Thread 4 executing
    Thread 3 executing
    Thread 2 executing
    Thread 1 executing
    Thread 4 executing
    Thread 3 executing
    Thread 1 executing
    Thread 2 executing
    Thread 4 executing
    Final value of n is 5
    Final value of f.n (foo::n) is 5
    Final value of b.n (baz::n) is 0

### Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR | Applied to | Behavior as published | Correct behavior
--- | --- | --- | ---
LWG 2097 | C++11 | for overload (3), `F` could be `std::thread` | `F` is constrained
LWG 3476 | C++20 | overload (3) directly required (the decayed types of) `F` and the argument types to be move constructible | removed these requirements[1]

1. ↑ The move-constructibility is already indirectly required by std::is_constructible_v.

### References

- C++23 standard (ISO/IEC 14882:2024):

  - 33.4.3.3 thread constructors [thread.thread.constr]

- C++20 standard (ISO/IEC 14882:2020):

  - 32.4.2.2 thread constructors [thread.thread.constr]

- C++17 standard (ISO/IEC 14882:2017):

  - 33.3.2.2 thread constructors [thread.thread.constr]

- C++14 standard (ISO/IEC 14882:2014):

  - 30.3.1.2 thread constructors [thread.thread.constr]

- C++11 standard (ISO/IEC 14882:2011):

  - 30.3.1.2 thread constructors [thread.thread.constr]

### See also

(constructor) | constructs new `jthread` object (public member function of `std::jthread`)
C documentation for thrd_create

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/thread/thread/thread&oldid=169925"