SoftBank Robotics documentation What's new in NAOqi 2.8?

qi.async, qi.PeriodicTask API

Introduction

qi.async() and qi.PeriodicTask allow managing concurrent tasks.

Use of these should be preferred over classic threading.Thread or threading.Timer operations.

Thread creation and destruction are low-level operations that take resources for context switching each time they happen.

Using qi operations will let the system manage the low level operations and improve its overall performance.

qi.async

Launch an operation in a concurrent task.

The qi.future returned can be used to interact with the operation. (cancel, get return value ...)

qi.async(callback [, delay=usec] [, arg1, ..., argn]) → future
Parameters:
  • callback – the callback that will be called
  • delay – an optional delay in microseconds
Returns:

a future with the return value of the function

Warning

Canceling the async operation is possible while it is delayed.

Once the callback is called, cancel will not stop it in the middle of its execution.

qi.PeriodicTask

Execute an operation periodically and asynchronously.

By default, we do not compensate the callback time. The period will be constant between the end of a call and the beginning of another.

class qi.PeriodicTask
asyncStop()

Can be called from within the callback function Request for periodic task to stop asynchronously

compensateCallbackTime(compensate)
Parameters:compensate – boolean. True to activate the compensation.

When compensation is activated, call interval will take into account call duration to maintain the period.

Warning

when the callback is longer than the period specified, compensation will result in the callback being called successively without pause

isRunning() → bool
Returns:true if task is running
isStopping() → bool
Returns:whether state is stopping or stopped.

Can be called from within the callback to know if stop() or asyncStop() was called.

setCallback(callable)
Parameters:callable – a python callable, could be a method or a function

set the callback used by the periodictask, this function can only be called once

setName(name)

Set name for debugging and tracking purpose

setUsPeriod(usPeriod)
Parameters:usPeriod – the period in microseconds

Set the call interval in microseconds. This call will wait until next callback invocation to apply the change. To apply the change immediately, use:

task.stop()
task.setUsPeriod()
task.start()
start(immediate)
Parameters:immediate – immediate if true, first schedule of the task will happen with no delay.

start the periodic task at specified period. No effect if already running

Warning

concurrent calls to start() and stop() will result in undefined behavior.

stop()

Stop the periodic task. When this function returns, the callback will not be called anymore. Can be called from within the callback function

Warning

concurrent calls to start() and stop() will result in undefined behavior.

PeriodicTask operations visualization

No compensation, task 3s, period 5s

v                                v
+-----------+                    +-----------
+  Task 3s  +      wait 5s       +  Task 3s  ...
+-----------+--------------------+-----------

Compensation, task 3s, period 5s

v                     v
+-----------+         +-----------
+  Task 3s  + wait 2s +  Task 3s  ...
+-----------+---------+-----------

Compensation, task 7s, period 5s

v                            v
+----------------------------+---------------------------+----
+         Task 7s            +         Task 7s           +  ...
+----------------------------+---------------------------+----

Examples

In the following examples, we assume we have a connected session. If you already have an application, use:

application.session.service("ALTextToSpeech")

If you don’t, then use that:

session = qi.Session()
session.connect("tcp://127.0.0.1:9559")

Doing something in 2 seconds and getting the result.

import qi

def getAnswerToLifeAndUniverse(a, b):
  return a + b

fut = qi.async(getAnswerToLifeAndUniverse, 40, 2, delay=2000000)
#do work while the result is being processed
print("Result:", fut.value())

Calling tts.say after 42 seconds.

import qi

#assume we have a connected session

tts = session.service("ALTextToSpeech")

fut = qi.async(tts.say, "42 seconds elapsed", delay=42000000)

#wait for the sentence to be said
fut.wait()

Calling tts.say every 10 seconds.

import qi
import time
import functools

#assume we have a connected session

tts = session.service("ALTextToSpeech")
sayHelloCallable = functools.partial(tts.say, "hello")

sayHelloTask = qi.PeriodicTask()
sayHelloTask.setCallback(sayHelloCallable)
sayHelloTask.setUsPeriod(10000000)
sayHelloTask.start(True)

time.sleep(30)
sayHelloTask.stop()

Canceling a delayed operation before its execution.

import qi
import time

def dummyAction():
  # do your operations here
  qi.info("async example", "My dummy action is over")

action = qi.async(dummyAction, delay=15000000)
time.sleep(5)
action.cancel()
action.wait()
if action.isCanceled():
  qi.info("async example", "dummyAction was canceled as expected")