# 标准库头文件 <future>

< cpp‎ | header

此头文件是线程支持库的一部分。

### 类
promise (C++11) | 存储一个值以进行异步获取 (类模板)
packaged_task (C++11) | 打包一个函数，存储其返回值以进行异步获取 (类模板)
future (C++11) | 等待被异步设置的值 (类模板)
shared_future (C++11) | 等待被异步设置的值（可能为其他 future 所引用） (类模板)
launch (C++11) | 指定 std::async 所用的运行策略 (枚举)
future_status (C++11) | 指定在 std::future 和 std::shared_future 上的定时等待的结果 (枚举)
future_error (C++11) | 报告与 future 或 promise 有关的错误 (类)
future_errc (C++11) | 鉴别 future 错误码 (枚举)
std::uses_allocator<std::promise> (C++11) | 特化 std::uses_allocator 类型特征 (类模板特化)
std::uses_allocator<std::packaged_task> (C++11)(C++17 前) | 特化 std::uses_allocator 类型特征 (类模板特化)
### 函数
async (C++11) | 异步运行一个函数（有可能在新线程中执行），并返回保有其结果的 std::future (函数模板)
future_category (C++11) | 鉴别 future 错误类别 (函数)
std::swap(std::promise) (C++11) | 特化 std::swap 算法 (函数模板)
std::swap(std::packaged_task) (C++11) | 特化 std::swap 算法 (函数模板)

### 概要

    namespace std {
      enum class future_errc {
        broken_promise = /* 由实现定义 */,
        future_already_retrieved = /* 由实现定义 */,
        promise_already_satisfied = /* 由实现定义 */,
        no_state = /* 由实现定义 */
      };

      enum class launch : /* 未指明 */ {
        async = /* 未指明 */,
        deferred = /* 未指明 */,
        /* 由实现定义 */
      };

      enum class future_status {
        ready,
        timeout,
        deferred
      };

      template<> struct is_error_code_enum<future_errc> : public true_type { };
      error_code make_error_code(future_errc e) noexcept;
      error_condition make_error_condition(future_errc e) noexcept;

      const error_category& future_category() noexcept;

      class future_error;

      template<class R> class promise;
      template<class R> class promise<R&>;
      template<> class promise<void>;

      template<class R>
        void swap(promise<R>& x, promise<R>& y) noexcept;

      template<class R, class Alloc>
        struct uses_allocator<promise<R>, Alloc>;

      template<class R> class future;
      template<class R> class future<R&>;
      template<> class future<void>;

      template<class R> class shared_future;
      template<class R> class shared_future<R&>;
      template<> class shared_future<void>;

      template<class> class packaged_task;  // 不定义
      template<class R, class... ArgTypes>
        class packaged_task<R(ArgTypes...)>;

      template<class R, class... ArgTypes>
        void swap(packaged_task<R(ArgTypes...)>&, packaged_task<R(ArgTypes...)>&) noexcept;

      template<class F, class... Args>
        [[nodiscard]] future<invoke_result_t<decay_t<F>, decay_t<Args>...>>
          async(F&& f, Args&&... args);
      template<class F, class... Args>
        [[nodiscard]] future<invoke_result_t<decay_t<F>, decay_t<Args>...>>
          async(launch policy, F&& f, Args&&... args);
    }

#### 类 std::future_error

    namespace std {
      class future_error : public logic_error {
      public:
        explicit future_error(future_errc e);

        const error_code& code() const noexcept;
        const char*       what() const noexcept;

      private:
        error_code ec_;             // 仅用于阐释
      };
    }

#### 类模板 std::promise

    namespace std {
      template<class R>
      class promise {
      public:
        promise();
        template<class Allocator>
          promise(allocator_arg_t, const Allocator& a);
        promise(promise&& rhs) noexcept;
        promise(const promise&) = delete;
        ~promise();

        // 赋值
        promise& operator=(promise&& rhs) noexcept;
        promise& operator=(const promise&) = delete;
        void swap(promise& other) noexcept;

        // 取得结果
        future<R> get_future();

        // 设置结果
        void set_value(/* 见描述 */);
        void set_exception(exception_ptr p);

        // 以延迟提醒设置结果
        void set_value_at_thread_exit(/* 见描述 */);
        void set_exception_at_thread_exit(exception_ptr p);
      };

      template<class R>
        void swap(promise<R>& x, promise<R>& y) noexcept;

      template<class R, class Alloc>
        struct uses_allocator<promise<R>, Alloc>;
    }

#### 类模板 std::future

    namespace std {
      template<class R>
      class future {
      public:
        future() noexcept;
        future(future&&) noexcept;
        future(const future&) = delete;
        ~future();
        future& operator=(const future&) = delete;
        future& operator=(future&&) noexcept;
        shared_future<R> share() noexcept;

        // 取得值
        /* 见描述 */ get();

        // functions to check state
        bool valid() const noexcept;

        void wait() const;
        template<class Rep, class Period>
          future_status wait_for(const chrono::duration<Rep, Period>& rel_time) const;
        template<class Clock, class Duration>
          future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
      };
    }

#### 类模板 std::shared_future

    namespace std {
      template<class R>
      class shared_future {
      public:
        shared_future() noexcept;
        shared_future(const shared_future& rhs) noexcept;
        shared_future(future<R>&&) noexcept;
        shared_future(shared_future&& rhs) noexcept;
        ~shared_future();
        shared_future& operator=(const shared_future& rhs) noexcept;
        shared_future& operator=(shared_future&& rhs) noexcept;

        // 取得值
        /* 见描述 */ get() const;

        // 检查状态的函数
        bool valid() const noexcept;

        void wait() const;
        template<class Rep, class Period>
          future_status wait_for(const chrono::duration<Rep, Period>& rel_time) const;
        template<class Clock, class Duration>
          future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
      };
    }

#### 类模板 std::packaged_task

    namespace std {
      template<class> class packaged_task;  // 不定义

      template<class R, class... ArgTypes>
      class packaged_task<R(ArgTypes...)> {
      public:
        // 构造与析构
        packaged_task() noexcept;
        template<class F>
          explicit packaged_task(F&& f);
        ~packaged_task();

        // 无复制
        packaged_task(const packaged_task&) = delete;
        packaged_task& operator=(const packaged_task&) = delete;

        // 移动支持
        packaged_task(packaged_task&& rhs) noexcept;
        packaged_task& operator=(packaged_task&& rhs) noexcept;
        void swap(packaged_task& other) noexcept;

        bool valid() const noexcept;

        // 结果取得
        future<R> get_future();

        // 执行
        void operator()(ArgTypes... );
        void make_ready_at_thread_exit(ArgTypes...);

        void reset();
      };

      template<class R, class... ArgTypes>
      packaged_task(R (*)(ArgTypes...)) -> packaged_task<R(ArgTypes...)>;

      template<class F> packaged_task(F) -> packaged_task</* 见描述 */>;

      template<class R, class... ArgTypes>
        void swap(packaged_task<R(ArgTypes...)>& x, packaged_task<R(ArgTypes...)>& y) noexcept;
    }