std::jthread(3)

🎀 NAME 🎀

okay bestie 💖 welcome to the C++ Standard Libary manual, section 3 — today’s main character is std::jthread. The NAME line is literally std::jthread - std::jthread, no notes, periodt.

---

✨ SYNOPSIS ✨

here’s the exact synopsis, bestie — do not freestyle this part:

Defined in header <thread>
class jthread;              (since C++20)

so what even is it? jthread is a class that represents a single thread of execution. It has the same general behavior as std::thread, except that jthread automatically rejoins on destruction, and it can be cancelled/stopped in certain situations.

Threads begin execution immediately upon construction of the associated thread object — pending any OS scheduling delays — starting at the top-level function provided as a constructor argument. The return value of the top-level function is ignored, and if it terminates by throwing an exception, std::terminate is called. The top-level function may communicate its return value or an exception to the caller via std::promise or by modifying shared variables (which may require synchronization, see std::mutex and std::atomic).

⚠️ fr fr: if that top-level function throws, std::terminate gets called. That’s the rule.

Unlike std::thread, the jthread logically holds an internal private member of type std::stop_source, which maintains a shared stop-state. The jthread constructor accepts a function that takes a std::stop_token as its first argument, which will be passed in by the jthread from its internal std::stop_source. This allows the function to check if stop has been requested during its execution, and return if it has.

std::jthread objects may also be in the state that does not represent any thread (after default construction, move from, detach, or join), and a thread of execution may be not associated with any jthread objects (after detach).

No two std::jthread objects may represent the same thread of execution; std::jthread is not CopyConstructible or CopyAssignable, although it is MoveConstructible and MoveAssignable. iconic, honestly.

---

🌸 Member types 🌸

member type → definition, lowkey table energy but in list form:

• id — std::thread::id
• native_handle_type (optional*) — std::thread::native_handle_type

---

💅 Member functions 💅

• constructor — constructs new jthread object (public member function)
• destructor — if the thread is joinable, then a stop is requested and the thread joins (public member function)
• operator= — moves the jthread object (public member function)

---

👀 Observers 👀

• joinable — checks whether the thread is joinable, i.e. potentially running in parallel context (public member function)
• get_id — returns the id of the thread (public member function)
• native_handle — returns the underlying implementation-defined thread handle (public member function)
• hardware_concurrency [static] — returns the number of concurrent threads supported by the implementation (public static member function)

---

🎀 Operations 🎀

• join — waits for the thread to finish its execution (public member function)
• detach — permits the thread to execute independently from the thread handle (public member function)
• swap — swaps two jthread objects (public member function)

🛑 Stop token handling 🛑

• get_stop_source — returns a stop_source object associated with the shared stop state of the thread (public member function)
• get_stop_token — returns a stop_token associated with the shared stop state of the thread (public member function)
• request_stop — requests execution stop via the shared stop state of the thread (public member function)

---

🌈 Non-member functions 🌈

• swap(std::jthread) — specializes the std::swap algorithm (C++20) (function)

---

⭐ Notes ⭐

feature-test macro tea ☕:

• __cpp_lib_jthread — value: 201911L; Std: (C++20); feature: Stop token and joining thread

---

🦋 See also 🦋

• thread — manages a separate thread (C++11) (class)

---

mwah 💋 this page came from source/version http://cppreference.com, dated 2024.06.10, and it’s the std::jthread(3) page — bye bestie, go write some safe threads 💖