libqi-api  2.8.7.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Public Member Functions | Protected Attributes | List of all members
qi::FutureBarrier< T > Class Template Reference

This class helps waiting for multiple futures at the same point. More...

#include <futurebarrier.hpp>

Public Member Functions

 FutureBarrier (FutureCallbackType async=FutureCallbackType_Async)
 FutureBarrier constructor taking no argument. More...
 
void addFuture (qi::Future< T > fut)
 Adds the future to the barrier. More...
 
Future< std::vector< Future< T > > > future ()
 Gets the future result for the barrier. More...
 

Protected Attributes

boost::shared_ptr
< detail::FutureBarrierPrivate
< T > > 
_p
 

Detailed Description

template<typename T>
class qi::FutureBarrier< T >

This class helps waiting for multiple futures at the same point.

* This class helps waiting for multiple futures at the same point. If you want
* to make several calls in a function and wait for all results at some point.
* (:cpp:func:`qi::waitForAll(std::vector<Future<T>>&)` and
* :cpp:func:`qi::waitForFirst(std::vector<Future<T>>&)` may help you
* for simple cases).
*
* :cpp:class:`qi::FutureBarrier` is used like a builder. You must give it the
* futures with :cpp:func:`qi::FutureBarrier<T>::addFuture(qi::Future<T>)`. On
* first call to :cpp:func:`qi::FutureBarrier<T>::future()`, barrier will be closed
* and won't except any more future. :cpp:func:`qi::FutureBarrier<T>::future()`
* returns the vector of all the futures given to the barrier.
*
* With this code, you can easily write asynchronous map code.
*
* Simple example: waitForAll
* **************************
*
* .. code-block:: cpp
*
*     void waitForAll(std::vector< Future<int> >& vect) {
*         qi::FutureBarrier<int> barrier;
*         std::vector< Future<int> >::iterator it;
*
*         for (it = vect.begin(); it != vect.end(); ++it) {
*             barrier.addFuture(*it);
*         }
*         barrier.future().wait();
*
*         // [1]: Do something here with all the results.
*     }
*
* This function is the simplest one you can write with FutureBarrier. Lets say
* you have a vector of futures and you want to wait for all of them before
* executing something, this is typically the kind of code you would write.
*
* .. note::
*
*     This function is already provided with the API in ``qi`` namespace,
*     as a templated implementation. Don't recode it.
*
* Complete example
* ****************
*
* .. code-block:: cpp
*
*     qi::Future<int> returnAsynchronouslyNumber(int number);
*     void mult42(qi::Promise<int> prom, qi::Future<int> number);
*     void sumList(qi::Promise<int> prom,
*                  qi::Future< std::vector< qi::Future<int> > > fut);
*
*     qi::Future<int> sum42ProductTable() {
*         qi::FutureBarrier barrier;
*
*         // [1]:
*         for (int i = 0; i < 10; ++i) {
*             // [1.1]:
*             qi::Future<int> fut = returnAsynchronouslyNumber(i);
*
*             qi::Promise<int> prom;
*             fut.connect(boost::bind(&mult42, prom, _1));
*             barrier.addFuture(prom.future());
*
*             // [1.2]
*         }
*
*         // The following line would hang until the results are ready:
*         // std::vector< qi::Future<int> > values = barrier.future();
*         // Vector would then contain promises results, when they are all
*         // ready, so [0, 42, 84, 126, 168, 210, 252, 294, 336, 378]
*
*         // [2]:
*         qi::Promise<int> res;
*         barrier.future().connect(boost::bind(&sumList, res, _1));
*         return res.future();
*     }
*
* This is a complete example of how to do a map. This is the standard usage
* of futures but within a loop. If you look at *[1.1]* part, you have an
* asynchronous call to returnAsynchronouslyNumber function, a treatment of this
* result with function *mult42* to which we give a promise and we use the future
* of the promise. Instead of returning it, we give it to the FutureBarrier.
*
* This is due to the fact that *[2]* needs *[1]* to be completely executed
* before executing, including the callback *mult42*. FutureBarrier makes sure of
* this synchronisation.
*
* Since it is returning a :cpp:class:`qi::Future`, you can connect to it using
* the standard pattern again and execute a callback (*sumList*) when all the
* results have been acquired. This is what *[2]* does.
*
* To summarize, this function will: use an asynchronous call to the identity
* function (just to have an asynchronous call), multiply all the results by 42,
* sum all the multiplied values (in the vector), and return it.
*
* .. note::
*
*     If you add any callback to the future after the call to
*     :cpp:func:`qi::FutureBarrier<T>::addFuture(qi::Future<T>)`,
*     replacing *[1.2]*, the callback on barrier's future will be executed
*     asynchronously with it. If you are not sure, always call
*     :cpp:func:`qi::FutureBarrier<T>::addFuture(qi::Future<T>)` in last.
* 
Deprecated:
since 2.4, use waitForAll

Definition at line 164 of file futurebarrier.hpp.

Constructor & Destructor Documentation

template<typename T>
qi::FutureBarrier< T >::FutureBarrier ( FutureCallbackType  async = FutureCallbackType_Async)
inline

FutureBarrier constructor taking no argument.

Definition at line 167 of file futurebarrier.hpp.

Member Function Documentation

template<typename T>
void qi::FutureBarrier< T >::addFuture ( qi::Future< T >  fut)
inline

Adds the future to the barrier.

Returns
Whether the future could be added.
* This adds the future to the barrier. It means barrier's future won't return
* until this one returns. It will also be added to the resulting vector.
*
* When :cpp:func:`qi::FutureBarrier::future()` has been called, this function
* will throw.
* 

Definition at line 188 of file futurebarrier.hpp.

template<typename T>
Future< std::vector< Future<T> > > qi::FutureBarrier< T >::future ( )
inline

Gets the future result for the barrier.

* Returns a future containing the vector of all the futures given to the barrier.
*
* .. warning::
*
*     Once called, you will not be able to add a new future to the barrier.
* 

Definition at line 209 of file futurebarrier.hpp.

Member Data Documentation

template<typename T>
boost::shared_ptr<detail::FutureBarrierPrivate<T> > qi::FutureBarrier< T >::_p
protected

Definition at line 215 of file futurebarrier.hpp.


The documentation for this class was generated from the following file: