| Home | Libraries | People | FAQ | More

### Futures

##### Overview

The futures library provides a means of handling asynchronous future values, whether those values are generated by another fiber, or on a single fiber in response to external stimuli, or on-demand.

This is done through the provision of four class templates: `future<>` and `shared_future<>` which are used to retrieve the asynchronous results, and `promise<>` and `packaged_task<>` which are used to generate the asynchronous results.

An instance of `future<>` holds the one and only reference to a result. Ownership can be transferred between instances using the move constructor or move-assignment operator, but at most one instance holds a reference to a given asynchronous result. When the result is ready, it is returned from `future::get()` by rvalue-reference to allow the result to be moved or copied as appropriate for the type.

On the other hand, many instances of `shared_future<>` may reference the same result. Instances can be freely copied and assigned, and `shared_future::get()` returns a `const` reference so that multiple calls to `shared_future::get()` are safe. You can move an instance of `future<>` into an instance of `shared_future<>`, thus transferring ownership of the associated asynchronous result, but not vice-versa.

`fibers::async()` is a simple way of running asynchronous tasks. A call to `async()` spawns a fiber and returns a `future<>` that will deliver the result of the fiber function.

##### Creating asynchronous values

You can set the value in a future with either a `promise<>` or a `packaged_task<>`. A `packaged_task<>` is a callable object with `void` return that wraps a function or callable object returning the specified type. When the `packaged_task<>` is invoked, it invokes the contained function in turn, and populates a future with the contained function's return value. This is an answer to the perennial question: “How do I return a value from a fiber?” Package the function you wish to run as a `packaged_task<>` and pass the packaged task to the fiber constructor. The future retrieved from the packaged task can then be used to obtain the return value. If the function throws an exception, that is stored in the future in place of the return value.

    int calculate_the_answer_to_life_the_universe_and_everything() {
        return 42;
    }

    boost::fibers::packaged_task<int()> pt(calculate_the_answer_to_life_the_universe_and_everything);
    boost::fibers::future<int> fi=pt.get_future();
    boost::fibers::fiber(std::move(pt)).detach(); // launch task on a fiber

    fi.wait(); // wait for it to finish

    assert(fi.is_ready());
    assert(fi.has_value());
    assert(!fi.has_exception());
    assert(fi.get()==42);

A `promise<>` is a bit more low level: it just provides explicit functions to store a value or an exception in the associated future. A promise can therefore be used where the value might come from more than one possible source.

    boost::fibers::promise<int> pi;
    boost::fibers::future<int> fi;
    fi=pi.get_future();

    pi.set_value(42);

    assert(fi.is_ready());
    assert(fi.has_value());
    assert(!fi.has_exception());
    assert(fi.get()==42);