std::inplace_stop_source
From cppreference.com
| Defined in header <stop_token>
|
||
class inplace_stop_source;
|
(since C++26) | |
A stoppable-source that is the sole owner of its stop-state. Unlike std::stop_source (which uses shared ownership via reference-counting), inplace_stop_source completely avoids dynamic memory allocation by embedding the stop-state directly within the object itself. It manages cooperative cancellation efficiently and produces lightweight, non-owning std::inplace_stop_token objects that point directly back to its embedded state.
Member functions
constructs new inplace_stop_source object (public member function) | |
destructs the inplace_stop_source object (public member function) | |
operator= [deleted] |
not copy/move-assignable (public member function) |
Modifiers | |
| makes a stop request for the associated stop-state (public member function) | |
Observers | |
| returns an std::inplace_stop_token for the associated stop-state (public member function) | |
stop_possible [static] |
returns true (an active std::inplace_stop_source always has an active stop-state) (public member function) |
| checks whether the associated stop-state has been requested to stop (public member function) | |
Notes
| Feature | std::stop_source (C++20) | std::inplace_stop_source (C++26) |
|---|---|---|
| Allocation | Heap-allocated (reference-counted managed state shared among tokens) | In-place/stack-allocated (embedded directly inside the source object) |
| Ownership | Shared ownership (the state lives as long as at least one source, token, or callback exists) | Sole ownership (the source object entirely owns the state) |
| Token mechanics | Owning (increments/decrements reference count of the shared state) | Non-owning (holds a raw, lightweight pointer to the source’s embedded state) |
| Copy/move semantics | Copyable/movable (shares or transfers ownership of the state) | Non-copyable/movable (tied permanently to its original memory location) |
| Lifetime restriction | State remains valid even if the originating std::stop_source goes out of scope | All associated tokens and callbacks become invalid if the std::inplace_stop_source is destroyed |
| Primary use-case |
General asynchronous pipelines, long-lived background jobs, and std::jthread | High-performance environments, execution frameworks (std::execution), and allocation-constrained/embedded systems |
| Feature-test macro | Value | Std | Feature |
|---|---|---|---|
__cpp_lib_senders |
202406L |
(C++26) | std::inplace_stop_source
|
Example
Run this code
#include <chrono>
#include <iostream>
#include <stop_token>
#include <thread>
using namespace std::chrono_literals;
void worker_thread(std::inplace_stop_token token)
{
// Register a stop callback that fires synchronously when request_stop() is called
std::inplace_stop_callback cleanup(token, []
{
std::cout << "[Callback] Stop requested! Aborting operations...\n" << std::flush;
});
// Poll the token regularly within the cooperative worker loop
std::cout << "[Worker] Job started. Working...\n" << std::flush;
while (!token.stop_requested())
std::this_thread::sleep_for(100ms);
std::cout << "[Worker] Exiting loop gracefully.\n" << std::flush;
}
int main()
{
std::inplace_stop_source source;
std::thread worker(worker_thread, source.get_token());
std::this_thread::sleep_for(500ms);
std::cout << "[Main] Triggering request_stop()...\n" << std::flush;
source.request_stop(); // Blocks until all callbacks finish executing
worker.join();
std::cout << "[Main] Worker joined cleanly.\n" << std::flush;
}
Possible output:
[Worker] Job started. Working...
[Main] Triggering request_stop()...
[Callback] Stop requested! Aborting operations...
[Worker] Exiting loop gracefully.
[Main] Worker joined cleanly.
See also
(C++20) |
class representing a request to stop one or more std::jthreads (class) |
(C++26) |
a stop token that references stop state of its associated std::inplace_stop_source object (class) |
External links
| 1. | NVIDIA: stdexec::inplace_stop_source — github.com
|
| 2. | Beman-project: execution::inplace_stop_source — github.com
|