The latest version of this topic can be found at <future>.
Include the standard header <future> to define template classes and supporting templates that simplify running a function—possibly in a separate thread—and retrieving its result. The result is either the value that is returned by the function or an exception that is emitted by the function but is not caught in the function.
This header uses Concurrency Runtime (ConcRT) so that you can use it together with other ConcRT mechanisms. For more information about ConcRT, see Concurrency Runtime.
In code that is compiled by using /clr or /clr:pure, this header is blocked.
An asynchronous provider stores the result of a function call. An asynchronous return object is 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. The program creates an asynchronous provider whenever it needs one and from that it 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.
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
packaged_task are asynchronous providers. The template classes
shared_future describe asynchronous return objects.
Each of the template classes
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.
The template classes
shared_future never block in their destructors, except in one case that's preserved for backward compatibility: Unlike all other futures, for a
future—or the last
shared_future—that's attached to a task started with
std::async, the destructor blocks if the task has not completed; that is, it blocks if this thread did not yet call
.wait() and the task is still running. The following usability note has been added to the description of
std::async in the draft standard: "[Note: If a future obtained from std::async is moved outside the local scope, other code that uses the future must be aware that the future’s destructor may block for the shared state to become ready.—end note]" In all other cases,
shared_future destructors are required and are guaranteed to never block.
|future Class||Describes an asynchronous return object.|
|future_error Class||Describes an exception object that can be thrown by methods of types that manage
|packaged_task Class||Describes an asynchronous provider that is a call wrapper and whose call signature is
|promise Class||Describes an asynchronous provider.|
|shared_future Class||Describes an asynchronous return object. In contrast with a
|is_error_code_enum Structure||Specialization that indicates that
|uses_allocator Structure||Specialization that always holds true.|
|async Function||Represents an asynchronous provider.|
|future_category Function||Returns a reference to the
|make_error_code Function||Creates an
|make_error_condition Function||Creates an
|swap Function||Exchanges the associated asynchronous state of one
|future_errc Enumeration||Supplies symbolic names for the errors that are reported by the
|future_status Enumeration||Supplies symbolic names for the reasons that a timed wait function can return.|
|launch Enumeration||Represents a bitmask type that describes the possible modes for the template function