std::stop_callback

在标头 `<stop_token>` 定义
template< class Callback > class stop_callback;		(C++20 起)

stop_callback 类模板提供一种为关联的 std::stop_token 对象注册回调函数的 RAII 对象类型，使得当该 std::stop_token 的关联 std::stop_source 被请求停止时将调用这个回调函数。

经由 stop_callback 构造函数注册的回调函数，在成功对该 stop_callback 的关联 std::stop_token 的std::stop_source 调用了 request_stop() 的同一线程中调用；或者若构造函数的注册前已请求了停止，则在构造此 stop_callback 的线程中调用。

可以对同一 std::stop_token 创建多个 stop_callback，这可以在相同或不同线程同时进行。对它们的执行顺序不提供保证，但它们将被同步调用；但已对 std::stop_token 请求停止后构造的 stop_callback，则如前所述。

若调用的回调经由异常退出，则调用 std::terminate。

std::stop_callback 非可复制构造 (CopyConstructible) 、可复制赋值 (CopyAssignable) 、可移动构造 (MoveConstructible) 亦非可移动赋值 (MoveAssignable) 。

模板形参 Callback 类型必须为 invocable 且为 destructible。忽略任何返回值。

成员类型

类型	定义
`callback_type`	`Callback`

成员函数

(构造函数)	构造新的 `stop_callback` 对象 (公开成员函数)
(析构函数)	析构 `stop_callback` 对象 (公开成员函数)
operator= [弃置]	`stop_callback` 不可赋值 (公开成员函数)

推导指引

示例

运行此代码

#include <chrono>
#include <condition_variable>
#include <iostream>
#include <mutex>
#include <sstream>
#include <thread>
 
using namespace std::chrono_literals;
 
// 使用一个辅助类进行原子 std::cout 流输出。
class Writer
{
    std::ostringstream buffer;
public:
    ~Writer()
    {
        std::cout << buffer.str();
    }
    Writer& operator<<(auto input)
    {
        buffer << input;
        return *this;
    }
};
 
int main()
{
    // 工作线程。
    // 它将等待直至被请求停止。
    std::jthread worker([] (std::stop_token stoken)
    {
        Writer() << "工作线程 id: " << std::this_thread::get_id() << '\n';
        std::mutex mutex;
        std::unique_lock lock(mutex);
        std::condition_variable_any().wait(lock, stoken,
            [&stoken] { return stoken.stop_requested(); });
    });
 
    // 在工作线程上注册停止回调。
    std::stop_callback callback(worker.get_stop_token(), []
    {
        Writer() << "执行了停止回调，线程: "
            << std::this_thread::get_id() << '\n';
    });
 
    // 可以提前销毁 stop_callback 对象以阻止其执行。
    {
        std::stop_callback scoped_callback(worker.get_stop_token(), []
        {
            // 这里不会执行。
            Writer() << "作用域内的停止回调被执行，线程: "
                << std::this_thread::get_id() << '\n';
        });
    }
 
    // 演示由哪个线程何时执行 stop_callback。
    // 定义停止函数。
    auto stopper_func = [&worker]
    {
        if (worker.request_stop())
            Writer() << "执行了停止请求，线程: "
                << std::this_thread::get_id() << '\n';
        else
            Writer() << "未执行停止请求，线程: "
                << std::this_thread::get_id() << '\n';
    };
 
    // 使多个线程竞争以停止工作线程。
    std::jthread stopper1(stopper_func);
    std::jthread stopper2(stopper_func);
    stopper1.join();
    stopper2.join();
 
    // 已经请求停止后，立即执行新的 stop_callback。
    Writer() << "主线程: " << std::this_thread::get_id() << '\n';
    std::stop_callback callback_after_stop(worker.get_stop_token(), []
    {
        Writer() << "执行了停止回调，线程: "
            << std::this_thread::get_id() << '\n';
    });
}

可能的输出：

工作线程 id: 140460265039616
执行了停止回调，线程: 140460256646912
执行了停止请求，线程: 140460256646912
未执行停止请求，线程: 140460248254208
主线程: 140460265043776
执行了停止回调，线程: 140460265043776

编译器支持
自立实现与有宿主实现
语言
标准库
标准库标头
具名要求
功能特性测试宏 (C++20)
语言支持库
概念库 (C++20)
元编程库 (C++11)
诊断库
通用工具库
字符串库
容器库
迭代器库
范围库 (C++20)
算法库
数值库
本地化库
输入/输出库
文件系统库 (C++17)
正则表达式库 (C++11)
并发支持库 (C++11)
技术规范
符号索引
外部库

std::stop_callback

成员类型

成员函数

推导指引

示例

导航