- Aldebaran documentation |
- C++ Libraries |
- index

libqi-api 2.8.7.4

- Main Page
- Related Pages
- Namespaces
- Classes
- Files
- Examples

- Class List
- Class Hierarchy
- Class Members

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:

- /home/opennao/work/release-2.8/sdk/libqi/qi/detail/futurebarrier.hpp