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 对象仅设计为使用一次。

每个 promise 都与一个共享状态关联，该共享状态包含一些状态信息和一个结果，该结果可能尚未评估，已评估为某个值（可能是 void）或已评估为异常。一个 promise 可以对共享状态执行三件事：

使其就绪：promise 将结果或异常存储在共享状态中。将状态标记为就绪，并解除任何等待与共享状态关联的 future 的线程的阻塞。
释放：promise 放弃其对共享状态的引用。如果这是最后一个此类引用，则共享状态将被销毁。除非这是由 std::async 创建的尚未就绪的共享状态，否则此操作不会阻塞。
放弃：promise 存储类型为 std::future_error 且错误码为 std::future_errc::broken_promise 的异常，使共享状态就绪，然后释放它。

promise 是 promise-future 通信通道的“推送”端：将值存储在共享状态中的操作与（如 std::memory_order 中所定义）成功返回的任何等待共享状态的函数（例如 std::future::get）同步。否则，对同一共享状态的并发访问可能会发生冲突：例如，std::shared_future::get 的多个调用者必须要么都是只读的，要么提供外部同步。

(构造函数)	构造 promise 对象 (公共成员函数) [编辑]
(析构函数)	销毁 promise 对象 (公共成员函数) [编辑]
operator=	赋值共享状态 (公共成员函数) [编辑]
swap	交换两个 promise 对象 (公共成员函数) [编辑]
Getting the result
get_future	返回与承诺结果关联的 `future` (公共成员函数) [编辑]
Setting the result
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); // 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

编译器支持
自由（freestanding）与宿主（hosted）
语言
标准库
标准库头文件
具名要求
特性测试宏 (C++20)
语言支持库
概念库 (C++20)
诊断库
内存管理库
元编程库 (C++11)
通用工具库
容器库
迭代器库
范围库 (C++20)
算法库
字符串库
文本处理库
数值库
日期和时间库
输入/输出库
文件系统库 (C++17)
并发支持库 (C++11)
执行控制库 (C++26)
技术规范
符号索引
外部库

成员函数
promise::promise
promise::~promise
promise::operator=
promise::swap
Getting the result
promise::get_future
Setting the result
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>

cppreference.cn

命名空间

变体

视图

操作

std::promise

目录

[编辑] 成员函数

Getting the result

Setting the result

[编辑] 非成员函数

[编辑] 辅助类

[编辑] 示例

导航

工具箱