std::stop_token 协作取消 ​

什么是协作取消 ​

C++20 引入了一套协作取消机制,由三个类组成:

  • std::stop_source:发出停止请求的一方,持有共享的停止状态
  • std::stop_token:接收停止请求的一方,查询是否有停止请求
  • std::stop_callback:注册回调,在停止请求发出时自动调用

这套机制是"协作"的——发出 request_stop() 并不会强制终止线程,而是设置一个标志,线程需要主动检查 stop_requested() 并自行退出。

cpp
// 三者的关系:
// stop_source --(发出请求)--> 共享停止状态 <--(查询状态)-- stop_token
//                                    |
//                              stop_callback(自动触发)

基本示例 ​

cpp
#include <iostream>
#include <thread>
#include <stop_token>
#include <chrono>
#include <mutex>
#include <string>
#include <vector>
#include <condition_variable>

std::mutex cout_mutex;

void safe_print(const std::string& msg) {
    std::lock_guard<std::mutex> lock(cout_mutex);
    std::cout << msg << std::endl;
}

// ============================
// 示例1:stop_source 和 stop_token 基本用法
// ============================

void basic_demo() {
    std::stop_source source;
    std::stop_token token = source.get_token();

    std::cout << std::boolalpha;
    std::cout << "stop_possible: " << token.stop_possible() << std::endl;   // true
    std::cout << "stop_requested: " << token.stop_requested() << std::endl; // false

    // 发出停止请求
    source.request_stop();

    std::cout << "stop_requested: " << token.stop_requested() << std::endl; // true
}

// ============================
// 示例2:在独立线程中使用
// ============================

void standalone_demo() {
    std::stop_source source;

    // 线程接收 stop_token
    std::thread worker([token = source.get_token()] {
        int count = 0;
        while (!token.stop_requested()) {
            count++;
            std::this_thread::sleep_for(std::chrono::milliseconds(50));
        }
        safe_print("工作线程退出,计数: " + std::to_string(count));
    });

    std::this_thread::sleep_for(std::chrono::milliseconds(200));
    source.request_stop();  // 请求停止
    worker.join();
}

// ============================
// 示例3:stop_callback——停止时的回调
// ============================

void callback_demo() {
    std::stop_source source;
    std::stop_token token = source.get_token();

    // 注册回调——停止请求发出时自动调用
    std::stop_callback cb1(token, [] {
        safe_print("  回调1: 停止请求已收到");
    });

    std::stop_callback cb2(token, [] {
        safe_print("  回调2: 正在清理资源...");
    });

    safe_print("发出停止请求...");
    source.request_stop();
    // 回调在 request_stop() 调用时同步执行
}

// ============================
// 示例4:已经停止后注册回调
// ============================

void late_callback_demo() {
    std::stop_source source;
    std::stop_token token = source.get_token();

    // 先停止
    source.request_stop();

    // 之后注册回调——立即执行
    std::stop_callback cb(token, [] {
        safe_print("  后注册的回调也会立即执行");
    });
}

// ============================
// 示例5:多个 token 共享同一个 source
// ============================

void shared_source_demo() {
    std::stop_source source;

    // 多个线程共享同一个 stop_source
    std::vector<std::thread> threads;

    for (int i = 0; i < 3; i++) {
        threads.emplace_back([token = source.get_token(), i] {
            while (!token.stop_requested()) {
                std::this_thread::sleep_for(std::chrono::milliseconds(50));
            }
            safe_print("  线程 " + std::to_string(i) + " 已停止");
        });
    }

    std::this_thread::sleep_for(std::chrono::milliseconds(150));

    // 一个 request_stop 同时通知所有线程
    source.request_stop();

    for (auto& t : threads) t.join();
    safe_print("所有线程已退出");
}

// ============================
// 示例6:stop_callback 与条件变量配合
// ============================

void condvar_demo() {
    std::stop_source source;
    std::mutex mtx;
    std::condition_variable_any cv;
    bool data_ready = false;

    std::thread worker([&, token = source.get_token()] {
        std::unique_lock lock(mtx);

        // condition_variable_any 支持 stop_token
        // 当收到停止请求或条件满足时返回
        bool result = cv.wait(lock, token, [&] { return data_ready; });

        if (result) {
            safe_print("  数据就绪,处理中...");
        } else {
            safe_print("  收到停止请求,放弃等待");
        }
    });

    std::this_thread::sleep_for(std::chrono::milliseconds(100));

    // 通过 stop 中断等待
    source.request_stop();
    worker.join();
}

// ============================
// 示例7:jthread 中的 stop_token
// ============================

void jthread_integration_demo() {
    // jthread 自动创建 stop_source 并传入 stop_token
    std::jthread jt([](std::stop_token stoken) {
        // 注册清理回调
        std::stop_callback cleanup(stoken, [] {
            safe_print("  清理回调:释放资源");
        });

        while (!stoken.stop_requested()) {
            safe_print("  工作中...");
            std::this_thread::sleep_for(std::chrono::milliseconds(50));
        }
        safe_print("  线程正常退出");
    });

    std::this_thread::sleep_for(std::chrono::milliseconds(150));
    // jt 析构时自动 request_stop + join
}

// ============================
// 示例8:stop_source 的拷贝和独立性
// ============================

void source_copy_demo() {
    std::stop_source source1;
    std::stop_source source2 = source1;  // 共享同一个停止状态
    std::stop_source source3;             // 独立的停止状态

    std::stop_token token1 = source1.get_token();
    std::stop_token token3 = source3.get_token();

    std::cout << std::boolalpha;

    // source2 和 source1 共享状态
    source2.request_stop();
    std::cout << "token1 停止: " << token1.stop_requested() << std::endl;  // true

    // source3 是独立的
    std::cout << "token3 停止: " << token3.stop_requested() << std::endl;  // false
}

int main() {
    std::cout << "=== 基本用法 ===" << std::endl;
    basic_demo();

    std::cout << "\n=== 独立线程 ===" << std::endl;
    standalone_demo();

    std::cout << "\n=== 回调 ===" << std::endl;
    callback_demo();

    std::cout << "\n=== 延迟回调 ===" << std::endl;
    late_callback_demo();

    std::cout << "\n=== 共享 source ===" << std::endl;
    shared_source_demo();

    std::cout << "\n=== 条件变量 ===" << std::endl;
    condvar_demo();

    std::cout << "\n=== jthread 集成 ===" << std::endl;
    jthread_integration_demo();

    std::cout << "\n=== source 拷贝 ===" << std::endl;
    source_copy_demo();

    return 0;
}

三个类的职责 ​

类职责线程安全
stop_source拥有停止状态,发出停止请求是
stop_token查询停止状态,不能发出请求是
stop_callback注册回调,停止时自动调用构造/析构非并发安全

适用场景 ​

  • 后台工作线程的优雅停止
  • 一个信号同时停止多个线程
  • 中断阻塞的条件变量等待
  • 资源清理的回调注册
  • 与 jthread 配合的自动取消

常见问题 ​

request_stop 是线程安全的吗?

是的。可以从任何线程安全地调用 request_stop()。内部使用原子操作。

stop_callback 在哪个线程执行?

如果在 request_stop() 之前注册,回调在调用 request_stop() 的线程中同步执行。如果在 request_stop() 之后注册,回调在注册的线程中立即执行。

stop_callback 析构后会怎样?

回调被注销。如果 stop_callback 对象被销毁,它注册的回调不会再被调用(除非回调正在执行中,此时析构会等待回调完成)。

可以取消停止请求吗?

不可以。一旦 request_stop() 被调用,stop_requested() 永久为 true,不可逆。

注意事项 ​

  • request_stop() 是不可逆的——没有 reset
  • stop_callback 对象的生命周期决定了回调的有效期
  • stop_callback 的析构是阻塞的——如果回调正在执行,会等待完成
  • stop_source 的拷贝共享同一个停止状态
  • 默认构造的 stop_source 有有效的停止状态
  • 默认构造的 stop_token 没有关联的停止状态(stop_possible() 为 false)

总结 ​

C++20 的协作取消机制由 stop_source、stop_token 和 stop_callback 三部分组成。stop_source 发出停止请求,stop_token 查询停止状态,stop_callback 注册停止时的回调。整个机制是线程安全的,stop_source 可以在多个线程间共享,一个 request_stop() 通知所有持有相关 token 的线程。与 std::jthread 集成后,线程的停止和清理变得自动化和安全。这套机制是"协作"的——它只设置标志,线程必须主动检查并自行退出。