FreeBSD Manual Pages
std::thread::thread(3) C++ Standard Libary std::thread::thread(3) NAME std::thread::thread - std::thread::thread Synopsis thread() noexcept; (1) (since C++11) thread( thread&& other ) noexcept; (2) (since C++11) template< class F, class... Args > (3) (since C++11) explicit thread( F&& f, Args&&... args ); 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)), (until C++23) decay-copy(std::forward<Args>(args))...) std::invoke(auto(std::forward<F>(f)), (since C++23) auto(std::forward<Args>(args))...) 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. (until C++20) * 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. If any of the following is false, the program is ill-formed: * std::is_constructible_v<std::decay_t<F>, F> (since C++20) * (std::is_constructible_v<std::decay_t<Args>, Args> && ...) * std::is_invocable_v<std::decay_t<F>, std::decay_t<Args>...> 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 excep- tion may represent the error condition std::errc::resource_unavailable_try_again or an- other 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 excep- tions 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::millisec- onds(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::millisec- onds(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 retroac- tively 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 overload (3) directly required (the decayed LWG 3476 C++20 types of) removed these F and the argument types to be move requirements^[1] constructible 1. The move-constructibility is already indirectly required by std::is_constructible_v. References * C++23 standard (ISO/IEC 14882:2023): * 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 http://cppreference.com 2024.06.10 std::thread::thread(3)
NAME | Synopsis | Parameters | Postconditions | Exceptions | Notes | Example | Possible output: | References | See also
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::thread::thread&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>