|  | Home | Libraries | People | FAQ | More | 
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.
      
        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);