std::thread::thread
From cppreference.com
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 |
(until C++23) |
|
|
(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:
|
(until C++20) |
|
If any of the following is
|
(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] |
- ↑ 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
constructs new jthread object (public member function of std::jthread)
| |
C documentation for thrd_create
| |