`<future>`

[added with C++11]

async · future · future_category · future_errc · future_error · future_status · is_error_code_enum · launch · make_error_code · make_error_condition · packaged_task · promise · shared_future · swap · uses_allocator

Include the standard header <future> to define several template classes and supporting templates that simplify running a function, possibly in a separate thread, and retrieving its result. The result can be the value returned by the function or it can be an exception thrown during execution of the function and not caught inside the function.

An asynchronous provider stores the result of a function call. An asynchronous return object can be used to retrieve the result of a function call. An associated asynchronous state provides communication between an asynchronous provider and one or more asynchronous return objects. A program does not directly create any associated asynchronous state objects; rather, the program creates an asynchronous provider whenever it needs one and from that creates an asynchronous return object that shares its associated asynchronous state with the provider. Asynchronous providers and asynchronous return objects manage the objects that hold their shared associated asynchronous state; when the last object that references the associated asynchronous state releases it, the object that holds the associated asynchronous state is destroyed.

Here's an overview of the template classes defined in this header:

An asynchronous provider or an asynchronous return object that has no associated asynchronous state is empty.

An associated asynchronous state is ready only if its asynchronous provider has stored a return value or stored an exception.

The template function async and the template classes promise and packaged_task are asynchronous providers. The template classes future, and shared_future describe asynchronous return objects.

Each of the template classes promise, future, and shared_future has a specialization for the type void and a partial specialization for storing and retrieving a value by reference. These specializations differ from the primary template only in the signatures and semantics of the functions that store and retrieve the returned value.

namespace std {
        // ENUMERATION TYPES
enum class future_errc {
    broken_promise,
    future_already_retrieved,
    promise_already_satisfied,
    no_state
};

enum class future_status {
    ready,
    timeout,
    deferred
};

enum class launch {
    async = 1,  // exposition only
    deferred,
    any = async | deferred  // implementation defined addition
};

        // ERROR HANDLING
template<>
    struct is_error_code_enum<future_errc>
        : public true_type { };
error_code make_error_code(future_errc error) noexcept;
error_condition make_error_condition(future_errc error) noexcept;
const error_category& future_category() noexcept;
class future_error;

        // TEMPLATE CLASSES AND SPECIALIZATIONS
template<class Ty>
    class promise;
template<class Ty>
    class promise<Ty&>;
template<>
    class promise<void>;

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

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

template<class>
    class packaged_task; // not defined
template<class Ty, class... ArgTypes>
    class packaged_task<Ty(ArgTypes)>;

        // TEMPLATE FUNCTIONS
template<class Fn, class... ArgTypes>
    future<typename result_of<Fn(ArgTypes...)>::type>;
        async(Fn&& fn, ArgTypes&&... args);
template<class Fn, class... ArgTypes>
    future<typename result_of<Fn(ArgTypes...)>::type>;
        async(launch policy, Fn&& fn, ArgTypes&&... args);

template<class Ty>
    void swap(promise<Ty>& left, promise<Ty>& right) noexcept;
template<class Ty, class... ArgTypes>
    void swap(packaged_task<Ty(ArgTypes...)>& left,
        packaged_task<Ty(ArgTypes...)>& right) noexcept;

        // HELPERS
template<class Ty, class Alloc>
    struct uses_allocator<promise<Ty>, Alloc>;
template<class Ty, class Alloc>
    struct uses_allocator<packaged_task<Ty>, Alloc>;
}   // namespace std

`async`

template<class Fn, class... ArgTypes>
    future<typename result_of<Fn(ArgTypes...)>::type>;
        async(Fn&& fn, ArgTypes&&... args);
template<class Fn, class... ArgTypes>
    future<typename result_of<Fn(ArgTypes...)>::type>;
        async(launch policy, Fn&& fn, ArgTypes&&... args);

This discussion uses the following abbreviations:

dfn -- the result of calling decay_copy(forward<Fn>(fn))
dargs -- the results of the calls decay_copy(forward<ArgsTypes>(args...))
Ty -- the type result_of<Fn(ArgTypes...)>::type

Each template function is an asynchronous provider.

The first template function returns async(launch::any, fn, args...).

The second function returns an object of type future<Ty> whose associated asynchronous state holds, in addition to the potential result, the values of dfn and dargs and a thread object to manage a separate thread of execution.

Unless decay<Fn>::type is a type other than launch, the second function does not participate in overload resolution.

If policy is launch::any, the function may choose launch::async or launch::deferred. In this implementation the function uses launch::async.

If policy is launch::async, the function creates a new thread that evaluates INVOKE(dfn, dargs..., Ty). The function returns after creating the new thread, without waiting for any results. If the system cannot start a new thread, the function throws an exception object of type system_error holding an error code of resource_unavailable_try_again.

If policy is launch::deferred, the function marks its associated asynchronous state as holding a deferred function and returns. The first call to any non-timed function that waits for the associated asynchronous state to be ready effectively calls the deferred function by evaluating INVOKE(dfn, dargs..., Ty).

In all cases, the future object's associated asynchronous state is not set to ready until the evaluation of INVOKE(dfn, dargs..., Ty) completes, either by throwing an exception or by returning normally. The associated asynchronous state's result then holds the exception if there was one, otherwise the value, if any, returned by the evaluation.

`future`

future · get · operator= · share · valid · wait · wait_for · wait_until

template<class Ty>
    class future {
public:
    future() noexcept;
    future(future&& right) noexcept;
    future(const future& right) = delete;

    future& operator=(future&& right);
    future& operator=(const future& right) = delete;

    Ty get();
    bool valid() const noexcept;
    shared_future<Ty> share();

    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;
};

The template class describes an asynchronous return object. Every standard asynchronous provider returns an object whose type is an instantiation of this template. A future object provides the only access to the asynchronous provider that it is associated with. If you need multiple asynchronous return objects that are associated with the same asynchronous provider, copy the future object to a shared_future object.

When a future object is copied, its association with the asynchronous provider is transferred to the target object, leaving the original object empty.

Do not call any member functions other than valid, operator=, and the destructor on a future object that is empty.

Objects of type future are not synchronized. Calling member functions on the same object from multiple threads introduces a data race, with unpredictable results.

`future`

future() noexcept;
future(future&& right) noexcept;

The first constructor constructs an empty future object. The second constructor constructs a future object and transfers the associated asynchronous state associated with right to the newly constructed object, leaving right empty.

`future::get`

Ty future::get();

The member function blocks until the associated asynchronous state associated with this object is ready then retrieves the result stored in the associated asynchronous state. If the stored result is an exception, the function rethrows the exception. Otherwise, it returns the stored value.

For the partial specialization future<Ty&>, the stored value is effectively a reference to the object that was passed to the asynchronous provider as the return value.

For the specialization future<void> there is no stored value and the member function returns void.

Otherwise the function moves its return value from the stored value. Thus, it should be called only once.

`future::operator=`

future& operator=(future&& right) noexcept;

The operator transfers the associated asynchronous state associated with right to this object, leaving right empty. The operator returns *this.

`future::share`

shared_future<Ty> share();

The member function returns shared_future(move(*this)).

`future::valid`

bool valid() noexcept;

The member function returns true only if this object is not empty.

`future::wait`

void wait() const;

The member function blocks until the object's associated asynchronous state is ready.

`future::wait_for`

template<class Rep, class Period>
    future_status wait_for(
        const chrono::duration<Rep, Period>& rel_time) const;

The member function blocks until the object's associated asynchronous state is ready or until rel_time has elapsed.

The member function returns a value of type future_status that indicates the reason for returning.

`future::wait_until`

template<class Clock, class Duration>
    future_status wait_until(
        const chrono::time_point<Clock, Duration>& abs_time) const;

The member function blocks until the object's associated asynchronous state is ready or until the current time is later than abs_time.

The member function returns a value of type future_status that indicates the reason for returning.

`future_category`

const error_category& future_category() noexcept;

The function returns a reference to the error_category object that characterizes errors arising from futures.

`future_errc`

enum class future_errc {
    broken_promise,
    future_already_retrieved,
    promise_already_satisfied,
    no_state
};

The scoped enumeration supplies symbolic names for all the errors reported by the exception future_error.

`future_error`

class future_error
    : public logic_error {
public:
    future_error(error_code code);
    const error_code& code() const throw();
    const char *what() const throw();
};

The class describes an exception object that can be thrown by various member functions of types that manage futures.

`future_status`

enum class future_status {
    ready,
    timeout,
    deferred
};

The scoped enumeration supplies symbolic names for the reasons for a timed wait function to return:

future_status::ready if the associated asynchronous state is ready,
future_status::timedout if the time limit was reached, or
future_status::deferred if the associated asynchronous state holds a deferred function function that is not running.

`is_error_code_enum`

template<> is_error_code_enum<future_errc>
    : public true_type { };

The specialization of the type predicate always holds true, indicating that future_errc is an enumeration suitable for storing in an object of type error_code.

`launch`

enum class launch {
    async = 1,  // exposition only
    deferred,
    any = async | deferred  // implementation defined addition
};

The type is a bitmask type that describes the possible modes for the template function async.

`make_error_code`

error_code make_error_code(future_errc error) noexcept;

The function returns error_code(static_cast<int>(e), future_category()).

`make_error_condition`

error_condition make_error_condition(future_errc error) noexcept;

The function returns error_condition(static_cast<int>(e), future_category()).

`packaged_task`

get_future · operator= · operator() · make_ready_at_thread_exit · operator bool · packaged_task · ~packaged_task · reset · swap · valid

template<class>
    class packaged_task;    // not defined

template<class Ty, class... ArgTypes>
    class packaged_task<Ty(ArgTypes...)> {
public:
    packaged_task() noexcept;
    packaged_task(packaged_task&& right) noexcept;
    template<class Fn>
        explicit packaged_task(Fn&& fn);
    template<class Fn, class Alloc>
        explicit packaged_task(allocator_arg_t,
            const Alloc& alloc, Fn&& fn);
    ~packaged_task();
    packaged_task(packaged_task&) = delete;

    packaged_task& operator=(packaged_task&& right);
    packaged_task& operator=(packaged_task&) = delete;
    void swap(packaged_task& right) noexcept;

    explicit operator bool() const noexcept; [temporarily added with C++11]
    bool valid() const;

    future<Ty> get_future();

    void operator()(ArgTypes...);
    void make_ready_at_thread_exit(ArgTypes...);

    void reset();
};

The template class describes an asynchronous provider that is a call wrapper whose call signature is Ty(ArgTypes...). Its associated asynchronous state holds a copy of its callable object in addition to the potential result.

`packaged_task::get_future`

future<Ty> get_future();

If this object is empty, the member function throws an exception object of type future_error holding an error code of no_state.

Otherwise, if the member function has already been called for a packaged_task object with the same associated asynchronous state as this object, the member function throws an exception object of type future_error holding an error code of future_already_retrieved.

Otherwise, the member function returns an object of type future<Ty> that shares this object's associated asynchronous state.

`packaged_task::make_ready_at_thread_exit`

void make_ready_at_thread_exit(ArgTypes... args);

The member function behaves the same as operator()(args...), except that the associated asynchronous state is not set to ready until after all thread-local objects in the calling thread have been destroyed. Thus, threads blocked on the associated asynchronous state will typically not be unblocked until the calling thread exits.

`packaged_task::operator=`

packaged_task& operator=(packaged_task&& right);

The operator transfers the associated asynchronous state from right to this object, leaving right empty. The operator returns *this.

`packaged_task::operator()`

void operator()(ArgTypes... args);

If this object is empty, the member function throws an exception object of type future_error holding an error code of no_state.

Otherwise, if either of the member functions operator() or make_ready_at_thread_exit has already been called for this object, the member function throws an exception object of type future_error holding an error code of promise_already_satisfied.

Otherwise, the operator calls INVOKE(fn, args..., Ty), where fn is the callable object stored in this object's associated asynchronous state, and atomically stores the returned value, if any, as the returned result of this object's associated asynchronous state and sets that state to ready. As a result, any threads blocked on the associated asynchronous state become unblocked.

`packaged_task::operator bool`

operator bool() const noexcept;

The operator returns true only if this object is not empty.

`packaged_task::packaged_task`

packaged_task() noexcept;
packaged_task(packaged_task&& right) noexcept;
template<class Fn>
    explicit packaged_task(Fn&& fn);
template<class Fn, class Alloc>
    explicit packaged_task(allocator_arg_t,
        const Alloc& alloc, Fn&& fn);

The first constructor constructs an empty packaged_task object. The second constructor constructs a packaged_task object and transfers the associated asynchronous state associated with right to the newly constructed object, leaving right empty. The third constructor constructs a packaged_task object with a copy of fn stored in its associated asynchronous state. The fourth constructor constructs a packaged_task object with a copy of fn stored in its associated asynchronous state, using alloc for any memory allocations that are needed.

`packaged_task::~packaged_task`

~packaged_task();

If this object's associated asynchronous state is not ready, the destructor stores an exception of type future_error with an error code of broken_promise as the result in the associated asynchronous state. As a result, any threads blocked on the associated asynchronous state become unblocked.

`packaged_task::reset`

void reset();

Replaces this object's associated asynchronous state with a new associated asynchronous state, as if by *this = packaged_task(move(fn)), where fn is the function object stored in this object's associated asynchronous state. Thus, this object's state is cleared, and get_future, operator(), and make_ready_at_thread_exit can be called as if on a newly constructed object.

`packaged_task::swap`

void swap(packaged_task& right) noexcept;

The member function exchanges the associated asynchronous states of this object and right.

`packaged_task::valid`

bool valid() const;

The member function returns true only if this object is not empty.

`promise`

get_future · operator= · promise · set_exception · set_exception_at_thread_exit · set_value · set_value_at_thread_exit · swap

template<class Ty>
    class promise {
public:
    promise() noexcept;
    template<class Alloc>
        promise(allocator_arg_t, const Alloc& alloc);
    promise(promise&& right);
    promise(const promise& right) = delete;

    promise& operator=(promise&& right) noexcept;
    promise& operator=(promise& right) = delete;
    void swap(promise& right) noexcept;

    future<Ty> get_future();

    void set_value(see below);
    void set_exception(exception_ptr exc);

    void set_value_at_thread_exit(see below);
    void set_exception_at_thread_exit(exception_ptr exc);
};

The template class describes an asynchronous provider. It has member functions to set its result. It also has a member function that returns a future object that shares its associated asynchronous state. This member function can be called only once; subsequent calls throw an exception. This guarantee, in conjunction with the move-only semantics of the class template future, ensures that no more than one future object can be associated with any one promise object.

`promise::get_future`

future<Ty> get_future();

If this object is empty, the member function throws an exception object of type future_error holding an error code of no_state.

Otherwise, if the member function has already been called for a promise object with the same associated asynchronous state as this object, the member function throws an exception object of type future_error holding an error code of future_already_retrieved.

Otherwise, the member function returns an object of type future<Ty> that shares this object's associated asynchronous state.

`promise::operator=`

promise& operator=(promise&& right) noexcept;

The operator transfers the associated asynchronous state associated with right to this object, leaving right empty. The operator returns *this.

`promise::promise`

promise();
template<class Alloc>
    promise(allocator_arg_t, const Alloc& alloc);
promise(promise&& right) noexcept;

The first constructor constructs an empty promise object. The second constructor constructs an empty promise object, using alloc for any memory allocations that it needs. The third constructor constructs a promise object and transfers the associated asynchronous state associated with right to the newly constructed object, leaving right empty.

`promise::set_exception`

void set_exception(exception_ptr exc);

If this object is empty, the member function throws an exception object of type future_error holding an error code of no_state.

Otherwise, if any of the member functions set_exception, set_exception_at_thread_exit, set_value, or set_value_at_thread_exit has already been called for a promise object with the same associated asynchronous state as this object, the member function throws an exception object of type future_error holding an error code of promise_already_satisfied.

Otherwise, the member function atomically stores exc as the exception result of this promise object and sets the associated asynchronous state associated with this promise object to ready. As a result, any threads blocked on the associated asynchronous state become unblocked.

`promise::set_exception_at_thread_exit`

void set_exception_at_thread_exit(exception_ptr exc);

The member function behaves the same as set_exception, except that the associated asynchronous state is not set to ready until after all thread-local objects in the current thread have been destroyed. Thus, threads blocked on the associated asynchronous state will typically not be unblocked until the current thread exits.

`promise::set_value`

void promise::set_value(const Ty& value);
void promise::set_value(Ty&& value);
void promise<Ty&>::set_value(Ty& value);
void promise<void>::set_value();

If this object is empty, the member functions throw an exception object of type future_error holding an error code of no_state.

Otherwise, if any of the member functions set_exception, set_exception_at_thread_exit, set_value, or set_value_at_thread_exit has already been called for a promise object with the same associated asynchronous state as this object, the member functions throw an exception object of type future_error holding an error code of promise_already_satisfied.

Otherwise, the member functions atomically store value as the returned result of this promise object and set the associated asynchronous state associated with this promise object to ready. As a result, any threads blocked on the associated asynchronous state become unblocked.

The first function also throws any exception thrown when value is copied into the associated asynchronous state. If this occurs, the associated asynchronous state is not marked as ready.

The second function also throws any exception thrown when value is moved into the associated asynchronous state. If this occurs, the associated asynchronous state is not marked as ready.

For the partial specialization promise<Ty&>, the stored value is effectively a reference to the object that was passed to the set_value.

For the specialization promise<void> there is no stored value.

`promise::set_value_at_thread_exit`

void promise::set_value_at_thread_exit(const Ty& value);
void promise::set_value_at_thread_exit(Ty&& value);
void promise<Ty&>::set_value_at_thread_exit(Ty& value);
void promise<void>::set_value_at_thread_exit();

The member functions each behaves the same as set_value with the same argument list, except that the associated asynchronous state is not set to ready until after all thread-local objects in the current thread have been destroyed. Thus, threads blocked on the associated asynchronous state will typically not be unblocked until the current thread exits.

`promise::swap`

void swap(promise& right) noexcept;

The member function exchanges the associated asynchronous states of this object and right.

`shared_future`

get · operator= · shared_future · valid · wait · wait_for · wait_until

template<class Ty>
    class shared_future {
public:
    shared_future() noexcept;
    shared_future(future<Ty>&& right);
    shared_future(shared_future&& right) noexcept;
    shared_future(const shared_future& right);

    shared_future& operator=(shared_future&& right) noexcept;
    shared_future& operator=(const shared_future& right);

    see below get();
    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;
};

The template class describes an asynchronous return object. An asynchronous provider can be associated with any number of shared_future objects.

Do not call any member functions other than valid, operator=, and the destructor on a shared_future object that is empty.

Objects of type shared_future are not synchronized. Calling member functions on the same object from multiple threads introduces a data race, with unpredictable results.

`shared_future::get`

const Ty& shared_future::get();
Ty& shared_future<Ty&>::get();
void shared_future<void>::get();

Each of the functions blocks until the associated asynchronous state associated with this object is ready then retrieves the result stored in the associated asynchronous state. If the stored result is an exception, the function rethrows the exception. Otherwise, it returns the stored value.

For the partial specialization shared_future<Ty&>, the stored value is effectively a reference to the object that was passed to the asynchronous provider as the return value.

For the specialization shared_future<void> there is no stored value and the member function returns void.

`shared_future::operator=`

shared_future& operator=(shared_future&& right) noexcept;
shared_future& operator=(const shared_future& right);

The first operator transfers the associated asynchronous state associated with right to this object, leaving right empty. The second operator gives this object the same associated asynchronous state as right. The operators return *this.

`shared_future::shared_future`

shared_future() noexcept;
shared_future(future<Ty>&& right) noexcept;
shared_future(shared_future&& right) noexcept;
shared_future(const shared_future& right);

The first constructor constructs an empty shared_future object. The second and third constructors construct a shared_future object and transfer the associated asynchronous state associated with right to the newly constructed object, leaving right empty. The fourth constructor constructs a shared_future object with the same associated asynchronous state as right.

`shared_future::valid`

bool valid() noexcept;

The member function returns true only if this object is not empty.

`shared_future::wait`

void wait() const;

The member function blocks until the object's associated asynchronous state is ready.

`shared_future::wait_for`

template<class Rep, class Period>
    future_status wait_for(
        const chrono::duration<Rep, Period>& rel_time) const;

The member function blocks until the object's associated asynchronous state is ready or until rel_time has elapsed.

The member function returns a value of type future_status that indicates the reason for returning.

`shared_future::wait_until`

template<class Clock, class Duration>
    future_status wait_until(
        const chrono::time_point<Clock, Duration>& abs_time) const;

The member function blocks until the object's associated asynchronous state is ready or until the current time is later than abs_time.

The member function returns a value of type future_status that indicates the reason for returning.

`swap`

template<class Ty>
    void swap(promise<Ty>& left, promise<Ty>& right) noexcept;
template<class Ty, class... ArgTypes>
    void swap(packaged_task<Ty(ArgTypes...)>& left,
        packaged_task<Ty(ArgTypes...)>& right) noexcept;

Each template function calls x.swap(y).

`uses_allocator`

template<class Ty, class Alloc>
    struct uses_allocator<promise<Ty>, Alloc>
        : public true_type { };
template<class Ty, class Alloc>
    struct uses_allocator<packaged_task<Ty>, Alloc>
        : public true_type { };

The specializations always hold true.

See also the Table of Contents and the Index.