future-class.md

description	title	ms.date	f1_keywords	ms.assetid	helpviewer_keywords	ms.custom
Learn more about: future Class	future Class	06/15/2022	future/std::future future/std::future::future future/std::future::get future/std::future::share future/std::future::valid future/std::future::wait future/std::future::wait_for future/std::future::wait_until	495e82c3-5341-4e37-87dd-b40107fbdfb6	std::future [C++] std::future [C++], future std::future [C++], get std::future [C++], share std::future [C++], valid std::future [C++], wait std::future [C++], wait_for std::future [C++], wait_until	devdivchpfy22

future Class

Describes an asynchronous return object.

Syntax

template <class Ty>
class future;

Remarks

Each 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's 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.

Members

Public Constructors

Name	Description
future	Constructs a future object.

Public Methods

Name	Description
get	Retrieves the result that is stored in the associated asynchronous state.
share	Converts the object to a shared_future.
valid	Specifies whether the object isn't empty.
wait	Blocks the current thread until the associated asynchronous state is ready.
wait_for	Blocks until the associated asynchronous state is ready or until the specified time has elapsed.
wait_until	Blocks until the associated asynchronous state is ready or until a specified point in time.

Public Operators

Name	Description
future::operator=	Transfers the associated asynchronous state from a specified object.

Requirements

Header: <future>

Namespace: std

Constructors

Constructs a future object.

future() noexcept;
future(future&& Other) noexcept;

Parameters

Other
A future object.

Remarks

The first constructor constructs a future object that has no associated asynchronous state.

The second constructor constructs a future object and transfers the associated asynchronous state from Other. Other no longer has an associated asynchronous state.

get

Retrieves the result that is stored in the associated asynchronous state.

Ty get();

Return Value

If the result is an exception, the method rethrows it. Otherwise, the result is returned.

Remarks

Before it retrieves the result, this method blocks the current thread until the associated asynchronous state is ready.

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.

Because no stored value exists for the specialization future<void>, the method returns void.

In other specializations, the method moves its return value from the stored value. Therefore, call this method only once.

operator=

Transfers an associated asynchronous state from a specified object.

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

Parameters

Right
A future object.

Return Value

*this

Remarks

After the transfer, Right no longer has an associated asynchronous state.

share

Converts the object to a shared_future object.

shared_future<Ty> share();

Return Value

shared_future(move(*this))

valid

Specifies whether the object has an associated asynchronous state.

bool valid() noexcept;

Return Value

true if the object has an associated asynchronous state; otherwise, false.

wait

Blocks the current thread until the associated asynchronous state is ready.

void wait() const;

Remarks

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

wait_for

Blocks the current thread until the associated asynchronous state is ready or until a specified time interval has elapsed.

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

Parameters

Rel_time
A chrono::duration object that specifies a maximum time interval that the thread blocks.

Return Value

A future_status that indicates the reason for returning.

Remarks

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

wait_until

Blocks the current thread until the associated asynchronous state is ready or until after a specified time point.

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

Parameters

Abs_time
A time_point object that specifies a time after which the thread can unblock.

Return Value

A future_status that indicates the reason for returning.

Remarks

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

See also

Header Files Reference
<future>