qi.Signal API

Introduction

Signal allows communication between threads. One thread emits events, other threads register callback to the signal, and process the events appropriately.

Warning

In Python services, signals must be created before registering the service on the session. The same rule holds also for functions and properties.

A type can be specified in the constructor of the signal, otherwise any number of value of any type is supported.

However, it is important to note that the signature you give to a signal constructor is only a hint and it is not enforced by libqi. Not respecting it will not cause your program to fail, but the other programs that expect your signal to give a certain value, especially in strongly typed languages.

If a signal has the signature “m”, it may be triggered with any number of argument, what counts is the moment it is triggered. For example, if you trigger it with one argument and a connected callback expects none, you will receive an error like Subscriber not compatible to signal signature: cannot convert m to ().

Warning

disconnect is a blocking method which will wait for the callback to finish (except if it’s called from withing the callback). The signal destruction is also blocking. These two cases may cause deadlocks in your code, be careful.

Signal lazy enabling

Sometimes, mainly for performance reasons, it is useful to only enable some code if a Signal has at least one subscriber. For example, if you have a signal humanDetected, you may want to enable the image processing code only if there is at least one subscriber to the signal to save CPU cycles.

This can be achieved by passing a callback to the Signal constructor, which receives a boolean as an argument. This function will be called synchronously each time the number of subscribers switches between 0 and 1.

def onConnect(c):
    if c:
        print "First connection"
    else:
        print "No more connections"

sig = qi.Signal('m', onConnect)
l1 = sig.connect(mycallback) # calls onConnect(True)
l2 = sig.connect(mycallback) # nothing happens
sig.disconnect(l1) # nothing happens
sig.disconnect(l2) # calls onConnect(False)

Reference

class qi.Signal

(*args)

trigger the signal. for example:

s = qi.Signal()
s(42)
s(42, 43)

connect(callback) → int

Parameters:callback – the callback that will be called when the signal is triggered Returns:the connection id of the registered callback.

Connect the signal to a callback, the callback will be called each time the signal is triggered. Use the id returned to unregister the callback

disconnect(id) → bool

Parameters:id – the connection id returned by connect Returns:true on success

Disconnect the callback associated to id.

disconnectAll() → bool

Returns:true on success

disconnect all callback associated to the signal. This function should be used very carefully. It’s extremely rare that it is needed.

Examples

import qi

def onSignal(value):
  print "signal value:", value

s = qi.Signal()

s.connect(onSignal)
#trigger the signal
s(42)