std::promise

在标头 `<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 只应当使用一次。

每个承诺体都与一个共享状态 关联，其中含有一些状态信息和一个结果，它可能尚未求值，已求值为一个值（可能为 void），或者求值为一个异常。承诺可以对共享状态做三件事：

使就绪：承诺体存储结果或异常于共享状态。标记共享状态为就绪，并除阻在该共享状态所关联的未来体上等待的任何线程。
释放：承诺体放弃其对共享状态的引用。若这是最后一个这种引用，则销毁共享状态。除非这是 std::async 所创建的未就绪的共享状态，否则此操作不阻塞。
抛弃：承诺体存储以 std::future_errc::broken_promise 为错误码的 std::future_error 类型的异常，令共享状态为就绪，然后释放它。

承诺体是承诺体-未来体交流通道的“推”端：向共享状态存储值的操作同步于（定义于 std::memory_order）任何在共享状态上等待的函数（如 std::future::get）的成功返回。其他情况下对共享状态的共时访问可能冲突：例如，std::shared_future::get 的多个调用方必须全都是只读，或提供外部同步。

成员函数

(构造函数)	构造承诺体对象 (公开成员函数)
(析构函数)	析构承诺体对象 (公开成员函数)
operator=	赋值共享状态 (公开成员函数)
swap	交换两个承诺体对象 (公开成员函数)
获取结果
get_future	返回与承诺的结果关联的 `future` (公开成员函数)
设置结果
set_value	设置结果为指定值 (公开成员函数)
set_value_at_thread_exit	设置结果为指定值，同时仅在线程退出时分发提醒 (公开成员函数)
set_exception	设置结果为指示异常 (公开成员函数)
set_exception_at_thread_exit	设置结果为指示异常，同时仅在线程退出时分发提醒 (公开成员函数)

非成员函数

std::swap(std::promise)

(C++11)

特化 std::swap 算法
(函数模板)

辅助类

std::uses_allocator<std::promise>

(C++11)

特化 std::uses_allocator 类型特征
(类模板特化)

示例

此示例展示能如何将 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); // 提醒 future
}
 
void do_work(std::promise<void> barrier)
{
    std::this_thread::sleep_for(std::chrono::seconds(1));
    barrier.set_value();
}
 
int main()
{
    // 演示用 promise<int> 在线程间传递结果。
    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() 将等待直至该 future 拥有合法结果并取得它
    // 无需在 get() 前调用 wait()
    // accumulate_future.wait(); // 等待结果
    std::cout << "result=" << accumulate_future.get() << '\n';
    work_thread.join(); // wait for thread completion
 
    // 演示用 promise<void> 在线程间对状态发信号
    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

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

成员函数
promise::promise
promise::~promise
promise::operator=
promise::swap
获取结果
promise::get_future
设置结果
promise::set_value
promise::set_value_at_thread_exit
promise::set_exception
promise::set_exception_at_thread_exit
非成员函数
swap(std::promise)
辅助类
uses_allocator<std::promise>

std::promise

成员函数

获取结果

设置结果

非成员函数

辅助类

示例

导航