std::promise
来自 cppreference.cn
| 定义于头文件 <future> |
||
| template< class R > class promise; |
(1) | (自 C++11 起) |
| template< class R > class promise<R&>; |
(2) | (自 C++11 起) |
| template<> class promise<void>; |
(3) | (自 C++11 起) |
1) 基础模板。
2) 非 void 特化，用于在线程之间传递对象。
3) void 特化，用于传递无状态事件。
类模板 std::promise 提供了一种机制来存储一个值或异常，该值或异常稍后通过由 std::promise 对象创建的 std::future 对象异步获取。请注意，std::promise 对象 предназначена 用于仅使用一次。
每个 promise 都与一个共享状态相关联，该状态包含一些状态信息和一个结果，该结果可能尚未求值、求值为一个值（可能是 void）或求值为一个异常。promise 可以对共享状态执行三项操作
- 就绪：promise 将结果或异常存储在共享状态中。标记状态为就绪，并解除阻塞任何等待与共享状态关联的 future 的线程。
- 释放：promise 放弃其对共享状态的引用。如果这是最后一个此类引用，则共享状态将被销毁。除非这是由 std::async 创建的尚未就绪的共享状态，否则此操作不会阻塞。
- 放弃：promise 存储类型为 std::future_error 的异常，错误代码为 std::future_errc::broken_promise，使共享状态就绪，然后释放它。
promise 是 promise-future 通信通道的“推送”端：在共享状态中存储值的操作与等待共享状态的任何函数（例如 std::future::get）的成功返回同步发生（如 std::memory_order 中所定义）。否则，对同一共享状态的并发访问可能会冲突：例如，std::shared_future::get 的多个调用者必须全部为只读或提供外部同步。
内容 |
[编辑] 成员函数
| 构造 promise 对象 (public member function) | |
| 析构 promise 对象 (public member function) | |
| 赋值共享状态 (public member function) | |
| 交换两个 promise 对象 (public member function) | |
获取结果 | |
| 返回与承诺结果关联的 future (public member function) | |
设置结果 | |
| 将结果设置为特定值 (public member function) | |
| 将结果设置为特定值，同时仅在线程退出时传递通知 (public member function) | |
| 设置结果以指示异常 (public member function) | |
| 设置结果以指示异常，同时仅在线程退出时传递通知 (public member function) | |
[编辑] 非成员函数
| (C++11) |
特化 std::swap 算法 (function template) |
[编辑] 辅助类
| 特化 std::uses_allocator 类型特征 (class template specialization) |
[编辑] 示例
此示例展示了 promise<int> 如何用作线程之间的信号。
运行此代码
#include <chrono> #include <future> #include <iostream> #include <numeric> #include <thread> #include <vector> void accumulate(std::vector<int>::iterator first, std::vector<int>::iterator last, std::promise<int> accumulate_promise) { int sum = std::accumulate(first, last, 0); accumulate_promise.set_value(sum); // Notify future } void do_work(std::promise<void> barrier) { std::this_thread::sleep_for(std::chrono::seconds(1)); barrier.set_value(); } int main() { // Demonstrate using promise<int> to transmit a result between threads. std::vector<int> numbers = {1, 2, 3, 4, 5, 6}; std::promise<int> accumulate_promise; std::future<int> accumulate_future = accumulate_promise.get_future(); std::thread work_thread(accumulate, numbers.begin(), numbers.end(), std::move(accumulate_promise)); // future::get() will wait until the future has a valid result and retrieves it. // Calling wait() before get() is not needed // accumulate_future.wait(); // wait for result std::cout << "result=" << accumulate_future.get() << '\n'; work_thread.join(); // wait for thread completion // Demonstrate using promise<void> to signal state between threads. std::promise<void> barrier; std::future<void> barrier_future = barrier.get_future(); std::thread new_work_thread(do_work, std::move(barrier)); barrier_future.wait(); new_work_thread.join(); }
输出
result=21
