std::jthread::request_stop(3)

💖 NAME 💖

okay bestie, welcome to std::jthread::request_stop(3) from the C++ Standard Libary manual ✨ The title and the name are literally both std::jthread::request_stop, and that's iconic in a "the man page said what it said" way 💅

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

✨ Synopsis ✨

bool request_stop() noexcept;  (since C++20)

So this little icon issues a stop request to the internal stop-state, if it has not yet already had stop requested 🫶

The determination is made atomically, and if stop was requested, the stop-state is atomically updated to avoid race conditions, such that:

• stop_requested() and stop_possible() can be concurrently invoked on other std::stop_tokens and std::stop_sources of the same shared stop-state.
• request_stop() can be concurrently invoked from multiple threads on the same jthread object or on other std::stop_source objects associated with the same stop-state, and only one will actually perform the stop request.

However, see the Notes section 👀

🎀 Parameters 🎀

(none) — literally no arguments, bestie. It just does the thing.

🌸 Return value 🌸

true if this invocation made a stop request, otherwise false.

🦋 Postconditions 🦋

For a std::stop_token retrieved by get_stop_token() or a std::stop_source retrieved by get_stop_source(), stop_requested() is true. Periodt.

💅 Notes 💅

Okay so here's the tea, and it's actually important 😭:

• If the request_stop() does issue a stop request (i.e., returns true), then any std::stop_callbacks registered for the same associated stop-state will be invoked synchronously, on the same thread request_stop() is issued on. If an invocation of a callback exits via an exception, std::terminate is called. 💀
• If a stop request has already been made, this function returns false. However there is no guarantee that another thread or std::stop_source object which has just (successfully) requested stop for the same stop-state is not still in the middle of invoking a std::stop_callback function.
• If the request_stop() does issue a stop request (i.e., returns true), then all condition variables of base type std::condition_variable_any registered with an interruptible wait for std::stop_tokens associated with the jthread's internal stop-state will be awoken.

🌈 Example 🌈

// Run this code

#include <chrono>
#include <condition_variable>
#include <iostream>
#include <mutex>
#include <thread>

using namespace std::chrono_literals;

int main()
{
    // A sleepy worker thread
    std::jthread sleepy_worker(
        [](std::stop_token stoken)
        {
            for (int i = 10; i; --i)
            {
                std::this_thread::sleep_for(300ms);
                if (stoken.stop_requested())
                {
                    std::cout << "Sleepy worker is requested to stop\n";
                    return;
                }
                std::cout << "Sleepy worker goes back to sleep\n";
            }
        });

    // A waiting worker thread
    // The condition variable will be awoken by the stop request.
    std::jthread waiting_worker(
        [](std::stop_token stoken)
        {
            std::mutex mutex;
            std::unique_lock lock(mutex);
            std::condition_variable_any().wait(lock, stoken, []{ return false; });
            std::cout << "Waiting worker is requested to stop\n";
            return;
        });

    // std::jthread::request_stop() can be called explicitly:
    std::cout << "Requesting stop of sleepy worker\n";
    sleepy_worker.request_stop();
    sleepy_worker.join();
    std::cout << "Sleepy worker joined\n";

    // Or automatically using RAII:
    // waiting_worker's destructor will call request_stop()
    // and join the thread automatically.
}

🍓 Possible output 🍓

Requesting stop of sleepy worker
Sleepy worker is requested to stop
Sleepy worker joined
Waiting worker is requested to stop

source/version: http://cppreference.com · date: 2024.06.10 · page: std::jthread::request_stop(3) — bye bestie, go stop those threads responsibly 💖✨