|
libqi-api
2.0.6.8
|
|
libqi-api
2.0.6.8
|
This class helps waiting on multiple futures at the same point. More...
#include <future.hpp>
Public Member Functions | |
| FutureBarrier (FutureCallbackType async=FutureCallbackType_Async) | |
| FutureBarrier constructor taking no argument. | |
| bool | addFuture (qi::Future< T > fut) |
| Adds the future to the barrier. | |
| Future< std::vector< Future< T > > > | future () |
| Gets the future result for the barrier. | |
Protected Attributes | |
| bool | _closed |
| Atomic< int > | _count |
| std::vector< Future< T > > | _futures |
| Promise< std::vector< Future < T > > > | _promise |
This class helps waiting on multiple futures at the same point.
* This class helps waiting on 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 calls and you eant to wait on 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 it = 0; it < 10; ++it) {
* // [1.1]:
* qi::Future<int> fut = returnAsynchronouslyNumber(it);
*
* 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 standart 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 (*sunList*) when all the
* results has been acquired. This what *[2]* does.
*
* To summaries, this function will: use an asynchronous call to the function
* identity (just to have an asynchronous call), multiply all the results with
* the number 42, and the sum the complete vector, to 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.
* Definition at line 511 of file future.hpp.
| qi::FutureBarrier< T >::FutureBarrier | ( | FutureCallbackType | async = FutureCallbackType_Async | ) | [inline] |
FutureBarrier constructor taking no argument.
Definition at line 514 of file future.hpp.
| qi::FutureBarrier< T >::addFuture | ( | qi::Future< T > | fut | ) | [inline] |
Adds the future to the barrier.
* 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 have no effect and return false. *
Definition at line 522 of file future.hpp.
| 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 534 of file future.hpp.
bool qi::FutureBarrier< T >::_closed [protected] |
Definition at line 540 of file future.hpp.
Atomic<int> qi::FutureBarrier< T >::_count [protected] |
Definition at line 541 of file future.hpp.
std::vector< Future<T> > qi::FutureBarrier< T >::_futures [protected] |
Definition at line 542 of file future.hpp.
Promise< std::vector< Future<T> > > qi::FutureBarrier< T >::_promise [protected] |
Definition at line 543 of file future.hpp.