NAME¶

std::jthread::jthread - std::jthread::jthread

Synopsis¶

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

Constructs new jthread object.

1) Creates new jthread object which does not represent a thread.
2) Move constructor. Constructs the jthread 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 jthread object and associates it with a thread of execution. The new
thread of execution starts executing

* std::invoke(std::move(f_copy), get_stop_token(), std::move(args_copy)...), if
the expression is valid; otherwise, it starts executing
* std::invoke(std::move(f_copy), std::move(args_copy)...).

In either case,

* f_copy is an object of type std::decay_t<Function> and constructed from
std::forward<Function>(f), and
* args_copy... are objects of types std::decay_t<Args>... and constructed from
std::forward<Args>(args)....

Constructions of these objects are executed in the context of the caller, so that
any exceptions thrown during evaluation and copying/moving of the arguments are
thrown in the current thread, without starting the new thread. The program is
ill-formed if any construction or the std::invoke call is invalid.
This constructor does not participate in overload resolution if
std::remove_cvref_t<Function> is the same type as jthread.
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 on the new
thread of execution.
4) The copy constructor is deleted; threads are not copyable. No two std::jthread
objects may represent the same thread of execution.

Parameters¶

other - another jthread object to construct this jthread 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::jthread::id() (i.e. joinable() returns false) and
get_stop_source().stop_possible() is false.
2) other.get_id() equal to std::jthread::id() and get_id() returns the value of
other.get_id() prior to the start of construction.
3) get_id() not equal to std::jthread::id() (i.e. joinable() returns true), and
get_stop_source().stop_possible() 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 <iostream>
#include <utility>
#include <thread>
#include <chrono>
using namespace std::literals;

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

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

class foo
{
public:
void bar()
{
for (int i = 0; i < 5; ++i) {
std::cout << "Thread 3 executing\n";
++n;
std::this_thread::sleep_for(10ms);
}
}
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(10ms);
}
}
int n = 0;
};

int main()
{
int n = 0;
foo f;
baz b;
std::jthread t0; // t0 is not a thread
std::jthread t1(f1, n + 1); // pass by value
std::jthread t2a(f2, std::ref(n)); // pass by reference
std::jthread t2b(std::move(t2a)); // t2b is now running f2(). t2a is no longer a thread
std::jthread t3(&foo::bar, &f); // t3 runs foo::bar() on object f
std::jthread t4(b); // t4 runs baz::operator() on a copy of object b
t1.join();
t2b.join();
t3.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';
// t4 joins on destruction
}

Possible output:¶

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

See also¶

constructor constructs new thread object
(public member function of std::thread)