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

# qi.Future API

## Introduction

Promise and Future are a way to synchronise data between multiples threads. The number of future associated to a promise is not limited. Promise is the setter, future is the getter. Basically, you have a task to do, that will return a value, you give it a Promise. Then you have others thread that depend on the result of that task, you give them future associated to that promise, the future will block until the value or an error is set by the promise.

## Reference

`qi.``FutureState`

  Constants that describe the state of the Future. This is the status returned by `qi.Future.wait()`

  qi.FutureState.None | The future is not bound.
  qi.FutureState.Running | The future is attached to a Promise.
  qi.FutureState.Canceled | The future has been canceled
  qi.FutureState.FinishedWithError | The future has finished and an error is available
  qi.FutureState.FinishedWithValue | The future has finished and a value is available

`qi.``FutureTimeout`

  Constants to use for timeout arguments.

  qi.FutureTimeout.None | Do not wait.
  qi.FutureTimeout.Infinite | Block forever

## Examples

Simple example:

    import qi
    import time
    import functools

    def doSomeWork(p):
      #do your work here instead of sleeping
      time.sleep(1)
      p.setValue(42)

    p = qi.Promise()
    f = p.future()
    qi.async(functools.partial(doSomeWork, p))
    print "result:", f.value()

With callback:

    import qi
    import time
    import functools

    def doSomeWork(p):
      #do your work here instead of sleeping
      time.sleep(1)
      p.setValue(42)

    def resultReady(f):
      if f.hasValue():
        print "Value:", f.value()
      elif f.hasError():
        print "Error:", f.error()

    p = qi.Promise()
    f = p.future()
    qi.async(functools.partial(doSomeWork, p))

    #resultReady will be called even if the result is already there.
    f.addCallback(resultReady)

## Cancellation support

In some situations, you will want to create asynchronous operations that can be interrupted in the middle of their execution. For that you can set a callback to the promise that will be called when someone asks for cancellation or just check for `isCancelRequested()` on the promise.

    import qi
    import time
    from functools import partial

    class FakeOperation:
        def doStep(self):
            time.sleep(0.3)
            print 'I executed one step'

        def longOperation(self, promise):
            "do steps or cancel before the end"
            for i in range(10):
                if promise.isCancelRequested():
                    print 'Cancel requested, aborting'
                    promise.setCanceled()
                    return
                self.doStep()
            # if an error occurred, promise.setError("error")
            # use setValue if everything went ok
            print 'longOperation finished'
            promise.setValue(None)

        def asyncLongOperation(self):
            "start long operation and return a future"
            promise = qi.Promise()
            qi.async(partial(self.longOperation, promise))
            return promise.future()

    m = FakeOperation()

    fut = m.asyncLongOperation()
    time.sleep(1)
    fut.cancel()

    assert fut.wait() == qi.FutureState.Canceled
    assert fut.isCanceled()
    assert fut.isFinished()

Glossary Site map Index Support Contact Legal Notices