Boost C++ Libraries

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