std::jthread:: jthread

From cppreference.com
C++
Concurrency support library
Threads
(C++11)
(C++20)
(C++17) (C++17)
this_thread namespace
(C++11)
(C++11)
Cooperative cancellation
Mutual exclusion
Generic lock management
Condition variables
(C++11)
(C++11)
(C++11)
(C++11)
Semaphores
(C++20) (C++20)
Latches and Barriers
(C++20)
(C++20)
Futures
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
Safe Reclamation
Hazard Pointers
(C++26)
(C++26)
(C++26)
Atomic types
(C++11)
(C++20)
(C++11)
Initialization of atomic types
(C++11) (deprecated in C++20)
(C++11) (deprecated in C++20)
(C++11)
Memory ordering
(C++11)
(C++11)
(C++11)
(C++11)
Free functions for atomic operations
(C++11) (C++11)
(C++11) (C++11)
(C++11) (C++11)
(C++11) (C++11) (C++11) (C++11)
(C++11) (C++11)
(C++11) (C++11)
(C++11) (C++11)
(C++11) (C++11)
(C++11) (C++11)
(C++26) (C++26)
(C++26) (C++26)
(C++11)
(C++20) (C++20)
(C++20)
(C++20)
Free functions for atomic flags
(C++11) (C++11)
(C++11) (C++11)
(C++20) (C++20)
(C++20) (C++20)
(C++20)
(C++20)
std::jthread
jthread ( ) noexcept ;
(1) (since C++20)
jthread ( jthread && other ) noexcept ;
(2) (since C++20)
template < class F, class ... Args >
explicit jthread ( F && f, Args && ... args ) ;
(3) (since C++20)
jthread ( const jthread & ) = delete ;
(4) (since C++20)

Constructs new std::jthread object.

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

The new thread of execution starts executing:

std:: invoke ( decay-copy ( std:: forward < F > ( f ) ) , get_stop_token ( ) ,
decay-copy ( std:: forward < Args > ( args ) ) ... ) 		(until C++23)

std:: invoke ( auto ( std:: forward < F > ( f ) ) , get_stop_token ( ) ,
auto ( std:: forward < Args > ( args ) ) ... )

(since C++23)

if the expression above is well-formed, otherwise starts executing:

std:: 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.
These overloads participate in overload resolution only if std:: remove_cvref_t < F > is not the same type as std::jthread .
If any of the following is false , the program is ill-formed:
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::jthread objects may represent the same thread of execution.

Parameters

other - another std::jthread object to construct this std::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 <chrono>
#include <iostream>
#include <thread>
#include <utility>
 
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 (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 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 .

See also

constructs new thread object
(public member function of std::thread )
C documentation for thrd_create
Retrieved from " https://en.cppreference.com/mwiki/index.php?title=cpp/thread/jthread/jthread&oldid=172094 "