15.8 Listeners

Listeners are triggered by changes in an entity’s status. For instance, maybe Connext found a matching DataReader for a DataWriter, or new data has arrived for a DataReader.

You can use either Listeners or WaitSets to be notified of events. WaitSets block a thread until data is available. This is the safest way to get data, because it does not affect any middleware threads. In contrast, Listeners allow an application to be called back from a Connext thread. This provides better latency than WaitSets, because the application can handle the event in the same thread that is generating the notification (so there is no time spent context-switching between threads).

There is also the possibility that notifications can be lost when using WaitSets, because most notifications contain a status update for only the most recent event. For example, imagine a system where a DataReader is trying to detect that DataWriters have lost liveliness. If two DataWriters lose liveliness at about the same, a listener that handles the on_liveliness_changed status will be called back once for each DataWriter that lost liveliness. When on_liveliness_changed is called back the first time, the LivelinessChangedStatus will contain the handle for one of the DataWriters, and the second time the callback is called it will contain the handle for the other DataWriter. However, if WaitSets are used and the DataWriters become not alive at about the same time, it's possible that by the time the WaitSet is notified that the first DataWriter has lost liveliness, the second one also loses liveliness, and the LivelinessChangedStatus contains only the most recent DataWriter to lose liveliness.

The danger of using Listeners is that they are called back from a Connext thread, so performing any slow processing in a Listener callback can degrade the performance of Connext (by causing lost data, lost liveliness, etc.).

This section describes Listeners and how to use them.