std::thread::thread

 

C++

Language

Standard library headers

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

 

Thread support library

Threads
thread (C++11)
hardware_destructive_interference_sizehardware_constructive_interference_size (C++17)(C++17)
this_thread namespace
get_id (C++11) yield (C++11)	sleep_for (C++11) sleep_until (C++11)
Mutual exclusion
mutex (C++11) recursive_mutex (C++11) shared_mutex (C++17)	timed_mutex (C++11) recursive_timed_mutex (C++11) shared_timed_mutex (C++14)
Generic lock management
lock_guard (C++11) unique_lock (C++11) shared_lock (C++14) defer_lock_ttry_to_lock_tadopt_lock_t (C++11)(C++11)(C++11)	lock (C++11) try_lock (C++11) defer_locktry_to_lockadopt_lock (C++11)(C++11)(C++11) once_flag (C++11) call_once (C++11)
Condition variables
condition_variable (C++11)
condition_variable_any (C++11)
notify_all_at_thread_exit (C++11)
cv_status (C++11)
Futures
promise (C++11) future (C++11) shared_future (C++11) packaged_task (C++11) async (C++11)	launch (C++11) future_status (C++11) future_error (C++11) future_category (C++11) future_errc (C++11)

 

std::thread

Member classes

thread::id

Member functions

thread::thread

thread::~thread

thread::operator=

Observers

thread::joinable

thread::get_id

thread::native_handle

thread::hardware_concurrency

Operations

thread::join

thread::detach

thread::swap

Non-member functions

std::swap

 

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

Constructs new thread object.

1) Creates new thread object which does not represent a thread.

2) Move constructor. Constructs the 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 new std::thread object and associates it with a thread of execution. First the constructor copies/moves all arguments (both the function object f and all args...) to thread-accessible storage as if by the function:

template <class T>
typename decay<T>::type decay_copy(T&& v) {
    return std::forward<T>(v);
}

Any exceptions thrown during evaluation and copying/moving of the arguments are thrown in the current thread, not the new thread.

The code that will be run in the new thread is defined as follows. Let's refer to value_args as t1, t2, ..., tN, where N is sizeof...(value_args)and value_args is the result of calling decay_copy as defined above. The following code will be run in the new thread:

• If f is pointer to a member function of class T, then it is called. The return value is ignored. Effectively, the following code is executed:

• (t1.*f)(t2, ..., tN) if the type of t1 is either T, reference to T or reference to type derived from T.
• ((*t1).*f)(t2, ..., tN) otherwise.

• If N == 1 and f is pointer to a member data object of a class, then it is accessed. The value of the object is ignored. Effectively, the following code is executed:

• t1.*f if and the type of t1 is either T, reference to T or reference to type derived from T.
• (*t1).*f otherwise.

• f is called as a pointer to a non-member function in all other cases. The return value is ignored. Effectively, f(t1, t2, ..., tN) is executed.

(C++14) This constructor does not participate in overload resolution if std::decay<Function>::type is the same type as std::thread.

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

1-2)

noexcept specification:  

noexcept

  

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 completion of the invocation of the constructor synchronizes-with (as defined in std::memory_order) the beginning of the invocation of the copy of f.

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 <iostream>
#include <utility>
#include <thread>
#include <chrono>
#include <functional>
#include <atomic>
 
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));
    }
}
 
int main()
{
    int n = 0;
    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
    t2.join();
    t4.join();
    std::cout << "Final value of n is " << n << '\n';
}

Possible output:

Thread 1 executing
Thread 2 executing
Thread 1 executing
Thread 2 executing
Thread 1 executing
Thread 2 executing
Thread 1 executing
Thread 2 executing
Thread 2 executing
Thread 1 executing
Final value of n is 5

References

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

• 30.3.1.2 thread constructors [thread.thread.constr]