C++11 promise

一 promise

• 前文 C++11 async 可知，异步操作的方式之一，是通过 std::async 接口调用可执行对象，然后通过 std::future 获得结果。
• 另一种常见方式是在指定的 std::thread 中执行，如何获取在 std::thread 中的执行结果？办法之一就是通过 std::promise。

二 定义

// 头文件 <future>
template< class R > class promise; (1)(C++11 起) // 空模板
template< class R > class promise<R&>; (2)(C++11 起) // 非 void 特化，用于在线程间交流对象
template<>          class promise<void>; (3)(C++11 起) // void 特化，用于交流无状态事件

• 类模板 std::promise 提供存储值或异常的设施。

• promise 对象与其 get_future() 接口返回的 future 对象构成 promise-future 交流通道。通道的 promise对象与 future 对象关联同一共享状态(shared state)， promise 对象是通道的 push 端，future 对象是通道的 pop 端。promise 存储值或异常到共享状态中，使共享状态就绪，future 通过get()异步获得结果。

• promise 对共享状态的三种处理

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

• std::promise 只应当使用一次。

  Note that the std::promise object is meant to be used only once.

三 成员函数

1. 构造

   promise(); (1)(C++11 起)
   template< class Alloc >
   promise( std::allocator_arg_t, const Alloc& alloc ); (2)(C++11 起)
   promise( promise&& other ) noexcept; (3)(C++11 起)
   promise( const promise& other ) = delete; (4)(C++11 起) // 不可复制构造
   

2. 析构

   ~promise(); (C++11 起) // 抛弃共享状态
   

• 若共享状态就绪，则释放它。若共享状态未就绪，则抛弃。

3. operator=

   promise& operator=( promise&& other ) noexcept; (1)(C++11 起)
   promise& operator=( const promise& rhs ) = delete; (2)(C++11 起) // 不可复制赋值
   

四 get_future

std::future<T> get_future(); (C++11 起)

• 若无共享状态，或已调用 get_future 则抛出异常。即仅可调用一次。
• 可通过 get_future 间接获得结果。

五 设置结果

1. set_value

• 设置结果为指定值, 并使状态就绪。

// (仅为泛型 promise 模板的成员)
void set_value( const R& value ) (1)(C++11 起)
void set_value( R&& value ); (2)(C++11 起)

// (仅为 promise<R&> 模板特化的成员)
void set_value( R& value ); (3)(C++11 起)
// (仅为 promise<void> 模板特化的成员)
void set_value(); (4)(C++11 起)

• demo

#include <algorithm>  // sort
#include <future>     // future promise
#include <iostream>   // cout cin endl
#include <iterator>   // istream_iterator back_inserter
#include <sstream>    // istringstream
#include <thread>     // thread
#include <vector>     // vector
#include <numeric>    // accumulate

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);  // 原子地存储 num 到共享状态，并令状态就绪
}
int main() {
  std::istringstream iss_numbers{"3 4 1 42 23 -23 93 2 -289 93"};
  std::vector<int> numbers;
  {
    // set_value (4)
    std::promise<void> numbers_promise;
    std::future<void> numbers_future = numbers_promise.get_future();
   
    std::thread t([&] {
      std::copy(std::istream_iterator<int>{iss_numbers},
                std::istream_iterator<int>{}, std::back_inserter(numbers));
      numbers_promise.set_value(); // 使状态就绪
    });
   
    numbers_future.wait();
    std::sort(numbers.begin(), numbers.end());
   
    for (int num : numbers)
      std::cout << num << ' ';
    std::cout << std::endl;
   
    t.join();
  }
  {
    // set_value (1)
    std::promise<int> accumulate_promise;
    std::future<int> accumulate_future = accumulate_promise.get_future();
    std::thread t(accumulate, numbers.begin(), numbers.end(),
                            std::move(accumulate_promise));

    std::cout << "result=" << accumulate_future.get() << '\n';
    t.join(); 
  }
}

• 结果

-289 -23 1 2 3 4 23 42 93 93
result=-51

2. set_value_at_thread_exit

• 原子地存储 value 到共享状态，而不立即令状态就绪。在当前线程退出时，销毁所有拥有线程局域存储期的对象后，再令状态就绪。

// (仅为泛型 promise 模板的成员)
void set_value_at_thread_exit( const R& value );(1)	(C++11 起)
void set_value_at_thread_exit( R&& value );(2)	(C++11 起)

// (仅为 promise<R&> 模板特化的成员)
void set_value_at_thread_exit( R& value );(3)	(C++11 起)
// (仅为 promise<void> 模板特化的成员)
void set_value_at_thread_exit();(4)	(C++11 起)

• demo

// set_value_at_thread_exit
using namespace std::chrono_literals;
std::promise<int> p;
std::future<int> f = p.get_future();
std::thread([&p] {
  std::this_thread::sleep_for(1s);
  p.set_value_at_thread_exit(9);
}).detach();

std::cout << "Waiting..." << std::flush;
f.wait();
std::cout << "Done!\nResult is: " << f.get() << std::endl;

• 结果

Waiting...Done!
Result is: 9

3. set_exception

• 存储异常指针 p 到共享状态中，并令状态就绪。

void set_exception( std::exception_ptr p );(C++11 起)

• demo

// set_exception
std::promise<int> p;
std::future<int> f = p.get_future();

std::thread t([&p] {
  try {
    throw std::runtime_error("Example");
  } catch (...) {
    try {
      // store anything thrown in the promise
      p.set_exception(std::current_exception());
    } catch (...) {
    }  // set_exception() may throw too
  }
});

try {
  std::cout << f.get();
} catch (const std::exception& e) {
  std::cout << "Exception from the thread: " << e.what() << std::endl;
}
t.join();

• 结果

Exception from the thread: Example

4. set_exception_at_thread_exit

• 存储异常指针 p 到共享状态中，而不立即使状态就绪。在当前线程退出时，销毁所有拥有线程局域存储期的变量后，再零状态就绪。

六 参考

cppreference-promise