# SoftBank Robotics documentation What's new in NAOqi 2.8?

# qi::Promise, qi::Future

The promise and future concepts allow one to provide a result asynchronously. The implementor creates a promise for the result and returns the future contained in the promise. The caller can then use the result of the future later.

You can see a complete usage example at the end of this document.

## Summary

Global Namespaces

- namespace qi

  Classes (namespace qi)

  - class qi::Future

    Functions (class qi::Future)

    qi::Future<T>::valueCopy

    qi::Future<T>::andThenRImpl

    qi::Future<T>::then

    qi::Future<T>::_connect

    qi::Future<T>::operator const ValueTypeCast&

    qi::Future<T>::uniqueId

    qi::Future<T>::thenR

    qi::Future<T>::Future

    qi::Future<T>::operator*

    qi::Future<T>::andThen

    qi::Future<T>::operator=

    qi::Future<T>::cancel

    qi::Future<T>::isCancelable

    qi::Future<T>::hasError

    qi::Future<T>::makeCanceler

    qi::Future<T>::hasValue

    qi::Future<T>::sync

    qi::Future<T>::isFinished

    qi::Future<T>::valueSharedPtr

    qi::Future<T>::thenRImpl

    qi::Future<T>::error

    qi::Future<T>::wait

    qi::Future<T>::waitUntil

    qi::Future<T>::operator<

    qi::Future<T>::value

    qi::Future<T>::isValid

    qi::Future<T>::isRunning

    qi::Future<T>::andThenR

    qi::Future<T>::isCanceled

    qi::Future<T>::operator==

    qi::Future<T>::waitFor

    qi::Future<T>::connectWithStrand

    qi::Future<T>::connect

  - class qi::Promise

    Functions (class qi::Promise)

    qi::Promise<T>::isCancelRequested

    qi::Promise<T>::Promise

    qi::Promise<T>::setOnCancel

    qi::Promise<T>::operator=

    qi::Promise<T>::setValue

    qi::Promise<T>::value

    qi::Promise<T>::~Promise

    qi::Promise<T>::trigger

    qi::Promise<T>::setError

    qi::Promise<T>::setCanceled

    qi::Promise<T>::future

  - class qi::FutureSync

    Functions (class qi::FutureSync)

    qi::FutureSync<T>::operator=

    qi::FutureSync<T>::operator<

    qi::FutureSync<T>::_connect

    qi::FutureSync<T>::isValid

    qi::FutureSync<T>::operator Future<T>

    qi::FutureSync<T>::wait

    qi::FutureSync<T>::valueSharedPtr

    qi::FutureSync<T>::value

    qi::FutureSync<T>::waitUntil

    qi::FutureSync<T>::uniqueId

    qi::FutureSync<T>::hasValue

    qi::FutureSync<T>::operator const typename Future<T>::ValueTypeCast&

    qi::FutureSync<T>::error

    qi::FutureSync<T>::isRunning

    qi::FutureSync<T>::isCancelable

    qi::FutureSync<T>::waitFor

    qi::FutureSync<T>::connect

    qi::FutureSync<T>::async

    qi::FutureSync<T>::isFinished

    qi::FutureSync<T>::FutureSync

    qi::FutureSync<T>::isCanceled

    qi::FutureSync<T>::hasError

    qi::FutureSync<T>::valueCopy

    qi::FutureSync<T>::cancel

    qi::FutureSync<T>::~FutureSync

  Functions (namespace qi)

  qi::PromiseNoop

## Detailed Description

### qi::Future

A `Future` provides a way to wait for and get the result of an asynchronous operation. It is the receiving end of a `qi::Future` - `qi::Promise` pair.

Future is templated by the type of the underlying value. void is permitted.

#### The different states of a Future

A future can be in multiple states represented by `FutureState`:

- FutureState_None: The Future is not tied to a Promise, and will never change state.
- FutureState_Running: The future is tied to a Promise, and the asynchronous operation has not finished yet.
- FutureState_Canceled: The operation was successfully canceled.
- FutureState_FinishedWithError: The operation finished with an error.
- FutureState_FinishedWithValue: The operation finished and its return value is available.

#### Getting the state and waiting for a Future

There are multiple ways to handle a future. The first is to use the `qi::Future<T>::value` method. In that case, the call will block until the Future leaves the running state. Then if a value if available, it will be returned. Otherwise a `FutureException` will be raised:

    qi::Future<int> someOperation();

    int callIt()
    {
      int i = someOperation().value(); // wait, then get the value or throw
      return i;
    }

If you do not wish to wait forever, or want to handle Future error without catching an exception, you can use `Future<T>::wait` (timeout): this function waits at most the specified time in milliseconds, and return a `FutureState`. You can then safely call `Future<T>::value` or `Future<T>::error`, if future is in state `FutureState_FinishedWithValue` or `FutureState_FinishedWithError` respectively:

    qi::Future<int> f = someOperation();
    switch(f.wait(1000))
    {
       case FutureState_Running:
         std::cerr << "Still not ready" << std::endl;
         break;
       case FutureState_Canceled:
         std::cerr << "Canceled" << std::endl;
         break;
       case FutureState_FinishedWithError:
         std::cerr << "Error: " << f.error() << std::endl;
         break;
       case FutureState_FinishedWithValue:
         std::cerr << "Value: " << f.value() << std::endl;
         break;
    }

#### Future notification

Alternatively, you can get notified of Future completion asynchronously using `Future<T>::connect`. This function accepts a callback function or functor with signature `void (qi::Future<T> f)`.

The Future guarantees you that your callback function will be called once and only once, when or if the Future leaves the Running state (that is, enters one of Canceled, FinishedWithError or FinishedWithValue):

    void myCallback(const qi::Future<int>& f)
    {
      qi::FutureState s = f.wait(); // will return immediately, Future has finished.
      switch(s) {...}
    }

    // ...
    qi::Future<int> f = someOperation();
    f.connect(&myCallback);

connect() accepts extra arguments after the callback: values or placeholders that will be bound to the call(similarly to how `boost::bind` works). If the first argument is a `boost::weak_ptr`, or inherits from `qi::Trackable`, then the callback will not be called if the weak_ptr cannot be locked, or if the Trackable was destroyed:

    class Foo
    {
    public:
      void onOpFinished(const qi::Future<int>& op, int opNumber);
    };

    void safe_async_op(boost::shared_ptr<Foo> foo, int opNumber)
    {
      qi::Future<int> future = someOperation();
      // This version will keep foo alive at least until the Future finished
      future.connect(&Foo::onOpFinished, foo, _1, opNumber);
      // This version is safe in case foo is destroyed before the Future finishes.
      future.connect(&Foo::onOpFinished, boost::weak_ptr<Foo>(foo), _1, opNumber);
    }

#### Future callback synchronousness

The callback can be run in two modes that we call Sync and Async. Async means that the callback will be run in its own thread. Sync means one of the two:

- if the future is finished when connect() is called, the callback is run on that same thread and connect() will block
- if the future is not yet finished when connect() is called, the callback will be run on the promise thread and setValue() will block

There are two parameters that influence if the call will be Sync or Async. The algorithm is the following:

- if the type argument in connect() is different from Auto, respect it
- if the type argument of the Promise constructor is different from Auto, respect it
- otherwise, be asynchronous

#### Future cancellation

An async operation that returns a Future can support cancellation.

You can try to abort the operation by calling `cancel`. Depending on the operation implementation and on the timing of your call, your cancel request might be ignored (for example, if it is received too late and a value is already available). But you can expect the Future to hastily leave the Running state one way or an other.

A helper container, `qi::ScopedFutureGroup`, can be used to manage a set of futures that must be cancelled once the container is destroyed. It helps managing automatically future cancelation when destroying a system which is represented by a class.

### qi::Promise

A `qi::Promise` is an object that can create and satisfy a `qi::Future`. Like Future, it has shared semantics (all copies of a Promise represent the same object). The next example illustrates it’s basic use case:

    qi::Future<int> myFunctionReturningAFuture()
    {
      qi::Promise<int> promise;
      // start an asynchronous operation, holding the promise
      // note that starting threads like that is bad practice, use qi::async
      boost::thread(someAsynchronousOp, promise);
      return promise.future();
    }

    void someAsynchronousOp(qi::Promise<int> promise)
    {
      try {
        int result = performSomeTask();
        promise.setValue(result);
      }
      catch(const std::exception& e)
      {
        promise.setError(e.what());
      }
    }

In plain English:

- Create a `Promise` and return the `future()` obtained with `Promise::future`.
- Transmit the Promise to the asynchronously executing code.
- Notify of successful completion with `Promise::setValue` or `Promise::setError`.
- Only one of the two functions above must be called, and only once per `Promise`.

#### Supporting cancellation

In order to support cancellation of your asynchronous operation you can either provide a callback with signature `void(qi::Promise<T>)` to the `Promise` constructor or use `Promise::isCancelRequested` to check at a given point if the user requested a cancellation.

If you provide a callback, it will be called if a cancellation request is received by a connected `Future`. This callback is expected to ensure that the connected `Future` hastily leaves the Running state, by calling one of `Promise::setValue`, `Promise::setError` and `Promise::setCanceled`. However this call does not have to be made synchronously in the cancellation callback.

You can see an example with cancellation support at the end of this document.

#### Controlling callback execution

When one of the three state-changing functions listed above is called on a Promise, callbacks registered to the connected Future will be invoked. You can control whether this invocation is made synchronously, or asynchronously using a thread from an internal thread pool, by passing one of FutureCallbackType_Sync and FutureCallbackType_Async to the Promise constructor.

### qi::FutureSync

`qi::FutureSync` is a lightweight wrapper on top of `qi::Future` that will wait on the `Future` in its destructor if the `Future` was ignored by the user.

It is intended to be used as a way to provide a default apparent synchronous-blocking behavior to a function, that can be changed into an asynchronous behavior by handling the resulting `FutureSync`.

#### Returning a FutureSync

You can simply change the returned type from `Future` to `FutureSync` in the basic example. The returned `Future` will transparently convert to a `FutureSync`.

#### Calling a function returning a FutureSync

`FutureSync` follow this simple rule: The destructor will call `Future::wait` from its destructor, unless:

- It is copied into another `Future` or `FutureSync`
- `FutureSync::async` or any of the Future function is called (`wait`, `connect`, ...)

`FutureSync` also has a cast operator that allows you to use the returned value transparently.

    qi::FutureSync<int> someFunction();

    void test()
    {
      someFunction(); // will wait
      qi::FutureSync<int> f = someFunction(); // will wait at end of scope
      someFunction().async();                 // will not wait
      qi::Future<int> f2 = someFunction();    // will not wait
      someFunction().value();                 // will wait, because of value()
      int val = someFunction();               // will wait, does the same as
                                              // value(), may throw on error
    }

### Implementing an asynchronous function

#### Simple implementation

Here is an example of an asynchronous function implementation that supports cancellation.

Let’s implement this class and make `calculate()` asynchronous.

    class Worker {
      public:
        int calculate();
    };

First, `calculate` must return a future and we must create a function to do the actual work.

    #include <qi/future.hpp>

    class Worker {
      public:
        qi::Future<int> calculate();

      private:
        void doWork(qi::Promise<int> promise);
    };

For the sake of this example, we’ll use a simple function to simulate work:

    void Worker::doWork(qi::Promise<int> promise)
    {
      int acc = 0;
      for (int i = 0; i < 100; ++i)
      {
        qi::os::msleep(10); // working...
        acc += 1;
      }
      promise.setValue(acc);
    }

And then, we must call this function asynchronously and return the corresponding future:

    qi::Future<int> Worker::calculate() {
      qi::Promise<int> promise;
      qi::async(boost::bind(&Worker::doWork, this, promise));
      return promise.future();
    }

Now, `calculate` is asynchronous! But this isn’t useful at all, our code is more complex and this could have been done just by calling `qi::async`. What we can do now is to support cancellation so that one can call `cancel()` on the returned future to abort the action.

#### Cancellation support

Promises can support cancellation either using a cancellation callback or checking if a cancel request has been made. This example shows the second solution.

    qi::Future<int> Worker::calculate() {
      qi::Promise<int> promise;
      qi::async(boost::bind(&Worker::doWork, this, promise));
      return promise.future();
    }

`doWork()` can now check if the future has been cancelled.

    void Worker::doWork(qi::Promise<int> promise)
    {
      int acc = 0;
      for (int i = 0; i < 100; ++i)
      {
        if (promise.isCancelRequested())
        {
          std::cout << "cancel requested" << std::endl;
          promise.setCanceled();
          return;
        }
        qi::os::msleep(10); // working...
        acc += 1;
      }
      promise.setValue(acc);
    }

## Reference

enum `qi::FutureState`

  Name | Brief
  --- | ---
  `FutureState_None` | Future is not tied to a promise.
  `FutureState_Running` | Operation pending.
  `FutureState_Canceled` | The future has been canceled.
  `FutureState_FinishedWithError` | The operation is finished with an error.
  `FutureState_FinishedWithValue` | The operation is finished with a value.

### qi::Future Class Reference

#### Introduction

`More...`

    #include <qi/future.hpp>

- Inherits: `qi::detail::AddUnwrap< T >`

#### Public Functions

``Future``()
``Future``(const Future<T>& b)
bool ``operator==``(const Future<T>& other) const
Future<T>& ``operator=``(const Future<T>& b)
bool ``operator<``(const Future<T>& b) const
FutureUniqueId ``uniqueId``() const
bool ``isValid``() const
``Future``(const ValueType& v, FutureCallbackType async)
const ValueType& ``value``(int msecs) const
const ValueType& ``value``(Either<MilliSeconds, Infinity> timeout) const
ValueType ``valueCopy``(Either<MilliSeconds, Infinity> timeout) const
boost::shared_ptr<const T> ``valueSharedPtr``(Either<MilliSeconds, Infinity> timeout) const
ValueType ``operator*``() const
``operator const ValueTypeCast&``() const
FutureState ``wait``(int msecs) const
FutureState ``wait``(qi::Duration duration) const
FutureState ``waitFor``(qi::Duration duration) const
FutureState ``wait``(qi::SteadyClock::time_point timepoint) const
FutureState ``waitUntil``(qi::SteadyClock::time_point timepoint) const
bool ``isFinished``() const
bool ``isRunning``() const
bool ``isCanceled``() const
bool ``hasError``(int msecs) const
bool ``hasValue``(int msecs) const
const std::string& ``error``(int msecs) const
FutureSync<T> ``sync``()
void ``cancel``()
bool ``isCancelable``() const
template<typename R, typename AF>
Future<R> ``thenR``(FutureCallbackType type, AF&& func)
template<typename R, typename AF>
Future<R> ``thenR``(AF&& func)
template<typename R, typename AF, typename Arg0, typename... Args>
````()
template<typename R, typename AF, typename Arg0, typename... Args>
````()
template<typename F>
auto ``then``(FutureCallbackType type, F&& func)
template<typename AF>
auto ``then``(AF&& func)
template<typename R, typename AF>
Future<R> ``andThenR``(FutureCallbackType type, AF&& func)
template<typename R, typename AF>
Future<R> ``andThenR``(AF&& func)
template<typename F>
auto ``andThen``(FutureCallbackType type, F&& func)
template<typename AF>
auto ``andThen``(AF&& func)
boost::function<void()> ``makeCanceler``()
template<typename AF>
void ``connect``(const AF& fun, FutureCallbackType type)
template<typename FUNCTYPE, typename ARG0>
void ``connect``(FUNCTYPE fun, ARG0 tracked, ..., FutureCallbackType type)
void ``connectWithStrand``(qi::Strand* strand, const boost::function<void(const Future<T>&)>& cb)
void ``connectWithStrand``(qi::Strand& strand, const boost::function<void(const Future<T>&)>& cb)
void ``_connect``(const boost::function<void()>& s)
template<typename R, typename F>
Future<R> ``thenRImpl``(FutureCallbackType callbackType, F&& continuation)
template<typename R, typename F>
Future<R> ``andThenRImpl``(FutureCallbackType callbackType, F&& continuation)

#### Types

typedef typename detail::FutureType< T >::type ValueType
typedef typename detail::FutureType< T >::typecast ValueTypeCast
typedef T TemplateValue
typedef boost::function< void(Future< T >)> Connection

#### Detailed Description

Class that represents a value that will be set later in time.

#### Function Documentation

`qi::Future<T>::``Future`()

`qi::Future<T>::``Future`(const Future<T>& b)

bool `qi::Future<T>::``operator==`(const Future<T>& other)`const`

Future<T>& `qi::Future<T>::``operator=`(const Future<T>& b)

bool `qi::Future<T>::``operator<`(const Future<T>& b)`const`

FutureUniqueId `qi::Future<T>::``uniqueId`()`const`

bool `qi::Future<T>::``isValid`()`const`

  Brief:

  Returns: | true if this future is associated to a promise, false otherwise.

`qi::Future<T>::``Future`(const ValueType& v, FutureCallbackType async = FutureCallbackType_Auto)

  Construct a Future that already contains a value.

const ValueType& `qi::Future<T>::``value`(int msecs = FutureTimeout_Infinite)`const`

  Brief: Return the value associated to a Future.

  Parameters: | msecs – timeout
  Returns: | the value

  This function can throw for many reason: wait timeoutuser errorfuture canceled

  if an error is set, then value throw a FutureUserException, others errors are FutureException.

const ValueType& `qi::Future<T>::``value`(Either<MilliSeconds, Infinity> timeout)`const`

ValueType `qi::Future<T>::``valueCopy`(Either<MilliSeconds, Infinity> timeout = Infinity{})`const`

  Return by copy the value associated to a Future.

boost::shared_ptr<const T> `qi::Future<T>::``valueSharedPtr`(Either<MilliSeconds, Infinity> timeout = Infinity{})`const`

  Return a shared pointer to the value associated to a Future.

ValueType `qi::Future<T>::``operator*`()`const`

`qi::Future<T>::``operator` const ValueTypeCast&()`const`

  same as value() with an infinite timeout.

FutureState `qi::Future<T>::``wait`(int msecs = FutureTimeout_Infinite)`const`

  Brief:

  Parameters: | msecs – Maximum time to wait in milliseconds, 0 means return immediately.
  Returns: | a FutureState corresponding to the state of the future.

  Wait for future to contain a value or an error

FutureState `qi::Future<T>::``wait`(qi::Duration duration)`const`

  Brief:

  Parameters: | duration – Maximum time to wait
  Returns: | a FutureState corresponding to the state of the future.

  Wait for future to contain a value or an error

FutureState `qi::Future<T>::``waitFor`(qi::Duration duration)`const`

FutureState `qi::Future<T>::``wait`(qi::SteadyClock::time_point timepoint)`const`

  Brief:

  Parameters: | timepoint – Time until which we can wait
  Returns: | a FutureState corresponding to the state of the future.

  Wait for future to contain a value or an error

FutureState `qi::Future<T>::``waitUntil`(qi::SteadyClock::time_point timepoint)`const`

bool `qi::Future<T>::``isFinished`()`const`

  Brief:

  Returns: | true if the future is finished do not throw

bool `qi::Future<T>::``isRunning`()`const`

  Brief:

  Returns: | true if the future is running do not throw

bool `qi::Future<T>::``isCanceled`()`const`

  Brief:

  Returns: | true if the future has been canceled This means that the future has been fully canceled, not that a cancel was requested. do not throw

bool `qi::Future<T>::``hasError`(int msecs = FutureTimeout_Infinite)`const`

  Brief:

  Parameters: | msecs – timeout
  Returns: | true if the future has an error. throw in the following case: timeout

bool `qi::Future<T>::``hasValue`(int msecs = FutureTimeout_Infinite)`const`

  Brief:

  Parameters: | msecs – timeout
  Returns: | true if the future has a value. throw in the following case: timeout

const std::string& `qi::Future<T>::``error`(int msecs = FutureTimeout_Infinite)`const`

  Brief:

  Parameters: | msecs –
  Returns: | the error throw on timeout throw if the future do not have an actual error.

FutureSync<T> `qi::Future<T>::``sync`()

  Make the future sync Should not be useful, use wait().

void `qi::Future<T>::``cancel`()

  cancel() the asynchronous operation if possible Exact effect is controlled by the cancel implementation, but it is expected to set a value or an error to the Future as fast as possible. Note that cancelation may be asynchronous.

bool `qi::Future<T>::``isCancelable`()`const`

  Brief:

  Returns: | always true

  Deprecatedsince 2.5

template<typename R, typename AF>

Brief: Execute a callback when the future is finished.

Returns: | a future that will receive the value returned by the callback or an error if the callback threw.

Future<R> `qi::Future<T>::``thenR`(FutureCallbackType type, AF&& func)

  The callback will receive this future as argument and all other arguments passed to this function.

  If the first argument bound to this function is a weak_ptr it will be locked. If it is a Trackable, the callback won’t be called after the object’s destruction. If it is an Actor, the call will be stranded.

  Deprecatedsince 2.5 use then()

template<typename R, typename AF>
Future<R> `qi::Future<T>::``thenR`(AF&& func)

  Deprecatedsince 2.5 use then()

`()`

`()`

template<typename F>

Brief: Execute a callback when the future is finished.

Returns: | a future that will receive the value returned by the callback or an error if the callback threw.

auto `qi::Future<T>::``then`(FutureCallbackType type, F&& func)

  The callback will receive this future as argument and all other arguments passed to this function.

  If the first argument bound to this function is a weak_ptr it will be locked. If it is a Trackable, the callback won’t be called after the object’s destruction. If it is an Actor, the call will be stranded.

template<typename AF>
auto `qi::Future<T>::``then`(AF&& func)

  Same as then(), but with type defaulted to FutureCallbackType_Auto.

template<typename R, typename AF>
Future<R> `qi::Future<T>::``andThenR`(FutureCallbackType type, AF&& func)

  The callback will receive the value of this future, as opposed to this future itself. In the case of Future<void>, the callback shall accept a void* parameter.

  If this future finishes with an error or a cancel, the callback will not be called and the returned future will finish in the same state.

  Deprecatedsince 2.5 use andThen()

template<typename R, typename AF>
Future<R> `qi::Future<T>::``andThenR`(AF&& func)

  Deprecatedsince 2.5 use andThen()

template<typename F>
auto `qi::Future<T>::``andThen`(FutureCallbackType type, F&& func)

  The callback will receive the value of this future, as opposed to this future itself. In the case of Future<void>, the callback shall accept a void* parameter.

  If this future finishes with an error or a cancel, the callback will not be called and the returned future will finish in the same state.

template<typename AF>
auto `qi::Future<T>::``andThen`(AF&& func)

  Same as andThen(), but with type defaulted to FutureCallbackType_Auto.

boost::function<void()> `qi::Future<T>::``makeCanceler`()

  This functor will not keep the future alive, which is useful to avoid reference cycles. If the future does not exist anymore, this is a no-op.

template<typename AF>
void `qi::Future<T>::``connect`(const AF& fun, FutureCallbackType type = FutureCallbackType_Auto)

  Connect a callback function that will be called once when the Future finishes (that is, switches from running to an other state).

  If type is sync, connect may block and call the callback synchronously if the future is already set.

  It guaranteed that your callback will be called exactly once (unless the promise is never set or the promise is reset, which is deprecated).

template<typename FUNCTYPE, typename ARG0>
void `qi::Future<T>::``connect`(FUNCTYPE fun, ARG0 tracked, ..., FutureCallbackType type = FutureCallbackType_Auto)

  Connect a callback with binding and tracking support.

  If the first argument is a weak_ptr or a pointer inheriting from qi::Trackable, the callback will not be called if tracked object was destroyed.

void `qi::Future<T>::``connectWithStrand`(qi::Strand* strand, const boost::function<void(const Future<T>&)>& cb)

  Deprecatedsince 2.5 use the overload with Strand&

void `qi::Future<T>::``connectWithStrand`(qi::Strand& strand, const boost::function<void(const Future<T>&)>& cb)

void `qi::Future<T>::``_connect`(const boost::function<void()>& s)

template<typename R, typename F>
Future<R> `qi::Future<T>::``thenRImpl`(FutureCallbackType callbackType, F&& continuation)

template<typename R, typename F>
Future<R> `qi::Future<T>::``andThenRImpl`(FutureCallbackType callbackType, F&& continuation)

### qi::Promise Class Reference

#### Introduction

`More...`

    #include <qi/future.hpp>

- Inherited by: `qi::detail::DelayedPromise< T >`

#### Public Functions

``Promise``(FutureCallbackType async)
template<typename FUNC, typename std::enable_if<!std::is_same< typename std::decay< FUNC >::type, typename std::decay< >
``Promise``(FUNC&& cancelCallback, FutureCallbackType async)
``Promise``(boost::function<void(qi::Promise<T>)> cancelCallback, FutureCallbackType async)
``Promise``(const qi::Promise<T>& rhs)
``~Promise``()
void ``setValue``(const ValueType& value)
void ``setError``(const std::string& msg)
void ``setCanceled``()
bool ``isCancelRequested``() const
Future<T> ``future``() const
ValueType& ``value``()
void ``trigger``()
void ``setOnCancel``(boost::function<void(qi::Promise<T>&)> cancelCallback)
Promise<T>& ``operator=``(const Promise<T>& rhs)

#### Types

typedef typename detail::FutureType< T >::type ValueType

#### Detailed Description

A Promise is used to create and satisfy a Future.

#### Function Documentation

`qi::Promise<T>::``Promise`(FutureCallbackType async = FutureCallbackType_Auto)

  Brief:

  Parameters: | async – specify how callbacks registered with Future::connect are called: synchronously from the Promise setter, or asynchronously from a thread pool.

  Create a standard promise.

template<typename FUNC, typename std::enable_if<!std::is_same< typename std::decay< FUNC >::type, typename std::decay< >
`qi::Promise<T>::``Promise`(FUNC&& cancelCallback, FutureCallbackType async = FutureCallbackType_Auto)

  Create a canceleable promise. If Future<T>::cancel is invoked, onCancel() will be called. It is expected to call setValue(), setError() or setCanceled() as quickly as possible, but can do so in an asynchronous way.

`qi::Promise<T>::``Promise`(boost::function<void(qi::Promise<T>)> cancelCallback, FutureCallbackType async = FutureCallbackType_Auto)

`qi::Promise<T>::``Promise`(const qi::Promise<T>& rhs)

`qi::Promise<T>::``~Promise`()

void `qi::Promise<T>::``setValue`(const ValueType& value)

  notify all future that a value has been set. throw if state != running If T is void value must be nullptr

void `qi::Promise<T>::``setError`(const std::string& msg)

  set the error, and notify all futures throw if state != running

void `qi::Promise<T>::``setCanceled`()

  set the cancel state, and notify all futures throw if state != running

bool `qi::Promise<T>::``isCancelRequested`()`const`

  return true if cancel has been called on the promise (even if the cancel callback did not run yet).

Future<T> `qi::Promise<T>::``future`()`const`

  Get a future linked to this promise. Can be called multiple times.

ValueType& `qi::Promise<T>::``value`()

  Gives access to the underlying value for in-place modification. trigger() must be called after the value is written to trigger the promise.

void `qi::Promise<T>::``trigger`()

  Trigger the promise with the current value.

void `qi::Promise<T>::``setOnCancel`(boost::function<void(qi::Promise<T>&)> cancelCallback)

  Set a cancel callback. If the cancel is requested, calls this callback immediately.

Promise<T>& `qi::Promise<T>::``operator=`(const Promise<T>& rhs)

### qi::FutureSync Class Reference

#### Introduction

`More...`

    #include <qi/future.hpp>

#### Public Functions

``FutureSync``()
``FutureSync``(const Future<T>& b)
``FutureSync``(const FutureSync<T>& b)
``FutureSync``(const ValueType& v)
FutureSync<T>& ``operator=``(const FutureSync<T>& b)
FutureSync<T>& ``operator=``(const Future<T>& b)
``~FutureSync``()
``operator Future<T>``()
bool ``operator<``(const FutureSync<T>& b) const
FutureUniqueId ``uniqueId``() const
const ValueType& ``value``(int msecs) const
ValueType ``valueCopy``(int msecs) const
boost::shared_ptr<const T> ``valueSharedPtr``(int msecs) const
``ValueTypeCast&``() const
FutureState ``wait``(int msecs) const
FutureState ``wait``(qi::Duration duration) const
FutureState ``waitFor``(qi::Duration duration) const
FutureState ``wait``(qi::SteadyClock::time_point timepoint) const
FutureState ``waitUntil``(qi::SteadyClock::time_point timepoint) const
bool ``isValid``() const
bool ``isRunning``() const
bool ``isFinished``() const
bool ``isCanceled``() const
bool ``hasError``(int msecs) const
bool ``hasValue``(int msecs) const
const std::string& ``error``(int msecs) const
void ``cancel``()
bool ``isCancelable``() const
void ``connect``(const Connection& s)
void ``_connect``(const boost::function<void()>& s)
template<typename FUNCTYPE, typename ARG0>
void ``connect``(FUNCTYPE fun, ARG0 tracked, ...)
Future<T> ``async``()

#### Types

typedef typename Future< T >::ValueType ValueType
typedef typename Future< T >::ValueTypeCast ValueTypeCast
typedef typename Future< T >::Connection Connection

#### Detailed Description

This class allow throwing on error and being synchronous when the future is not handled by the client.

This class should only be used as return type. If you want to store it, use qi::Future.

#### Function Documentation

`qi::FutureSync<T>::``FutureSync`()

`qi::FutureSync<T>::``FutureSync`(const Future<T>& b)

`qi::FutureSync<T>::``FutureSync`(const FutureSync<T>& b)

`qi::FutureSync<T>::``FutureSync`(const ValueType& v)

FutureSync<T>& `qi::FutureSync<T>::``operator=`(const FutureSync<T>& b)

FutureSync<T>& `qi::FutureSync<T>::``operator=`(const Future<T>& b)

`qi::FutureSync<T>::``~FutureSync`()

  will block until the future returns if the future is kept synchronous

`qi::FutureSync<T>::``operator` Future<T>()

bool `qi::FutureSync<T>::``operator<`(const FutureSync<T>& b)`const`

FutureUniqueId `qi::FutureSync<T>::``uniqueId`()`const`

const ValueType& `qi::FutureSync<T>::``value`(int msecs = FutureTimeout_Infinite)`const`

ValueType `qi::FutureSync<T>::``valueCopy`(int msecs = FutureTimeout_Infinite)`const`

boost::shared_ptr<const T> `qi::FutureSync<T>::``valueSharedPtr`(int msecs = FutureTimeout_Infinite)`const`

`qi::FutureSync<T>::``operator` const typename Future<T>::ValueTypeCast&()`const`

FutureState `qi::FutureSync<T>::``wait`(int msecs = FutureTimeout_Infinite)`const`

FutureState `qi::FutureSync<T>::``wait`(qi::Duration duration)`const`

FutureState `qi::FutureSync<T>::``waitFor`(qi::Duration duration)`const`

FutureState `qi::FutureSync<T>::``wait`(qi::SteadyClock::time_point timepoint)`const`

FutureState `qi::FutureSync<T>::``waitUntil`(qi::SteadyClock::time_point timepoint)`const`

bool `qi::FutureSync<T>::``isValid`()`const`

bool `qi::FutureSync<T>::``isRunning`()`const`

bool `qi::FutureSync<T>::``isFinished`()`const`

bool `qi::FutureSync<T>::``isCanceled`()`const`

bool `qi::FutureSync<T>::``hasError`(int msecs = FutureTimeout_Infinite)`const`

bool `qi::FutureSync<T>::``hasValue`(int msecs = FutureTimeout_Infinite)`const`

const std::string& `qi::FutureSync<T>::``error`(int msecs = FutureTimeout_Infinite)`const`

void `qi::FutureSync<T>::``cancel`()

bool `qi::FutureSync<T>::``isCancelable`()`const`

void `qi::FutureSync<T>::``connect`(const Connection& s)

void `qi::FutureSync<T>::``_connect`(const boost::function<void()>& s)

template<typename FUNCTYPE, typename ARG0>
void `qi::FutureSync<T>::``connect`(FUNCTYPE fun, ARG0 tracked, ...)

  Connect a callback with binding and tracking support.

  If the first argument is a weak_ptr or a pointer inheriting from qi::Trackable, the callback will not be called if tracked object was destroyed.

Future<T> `qi::FutureSync<T>::``async`()

template<typename T>
void `qi::``PromiseNoop`(qi::Promise<T>&)

  Helper function that does nothing on future cancelation

  Deprecatedsince 2.5:

Glossary Site map Index Support Contact Legal Notices