YARP  2.3.68+220-20170323.2+git4955ef0
Yet Another Robot Platform
Persistent connections
Paul Fitzpatrick

When a connection is made between two YARP ports, that connection lasts until it is explicitly disconnected by user action, or until one of the ports is closed.

It is also possible to specify connections that should be made whenever possible. These are called "persistent connections".

Normally, to connect two ports from the command line, you do:

yarp connect <source-port> <target-port> [optional-carrier]

for example:

yarp connect /src /dest mcast

If both the /src and /dest ports exist, this will create a connection between them that will last until it is disconnected by a matching call to "yarp disconnect", or until one of the ports closes.

To create a persistent connection, you instead do:

yarp connect --persist <source-port> <target-port> [optional-carrier]

for example:

yarp --persist connect /src /dest mcast

This command will succeed even if /src or /dest do not exist at the moment. Whenever a port called /src or /dest is created, YARP will check if it is possible to create this connection, and do so if it can.

An example of a persistent connection

For example, suppose we do:

yarp connect --persist /write /read

And then in two terminals we do:

yarp write /write
yarp read /read

The "yarp write" and "yarp read" programs will be connected automatically, and something typed on the "yarp write" console will appear on the "yarp read" console.

If either program is killed and restarted, the connection will reappear.

Listing persistent connections

To view all persistent connections, type:

yarp connect --persist

To view all persistent connections involving a particular port, type:

yarp connect --persist /port

Getting rid of a persistent connection

To stop the automatic creation of connections between two ports /src and /dest, do:

yarp disconnect --persist /src /dest

Persistence via topics

It is occasionally useful to view a collection of ports as a single "topic" to read from or write to. A topic can be created in YARP by doing:

yarp topic <topic-name>

For example:

yarp topic /topic

A topic can be thought of as a repeater port; anything it receives from any of its inputs, it resends to all its outputs. This bus-like behavior is often useful, but a bit inefficient. So in fact YARP topics are entirely virtual, with their effect achieved via direct connections between the ports connected to the virtual topic port.

To be concrete, here's how topics work. Persistent connections can be made between ports and a topic:

yarp connect --persist /src1 /topic
yarp connect --persist /src2 /topic
yarp connect --persist /src3 /topic
yarp connect --persist /topic /dest1
yarp connect --persist /topic /dest2
yarp connect --persist /topic /dest3

Every input to the topic will be connected to every output from the topic. For example, if all of the ports /src1, /src2, /dest1, and /dest2 exist, then the following connections will be made and maintained:

yarp connect /src1 /dest1
yarp connect /src1 /dest2
yarp connect /src1 /dest3
yarp connect /src2 /dest1
yarp connect /src2 /dest2
yarp connect /src2 /dest3
yarp connect /src3 /dest1
yarp connect /src3 /dest2
yarp connect /src3 /dest3

(if carriers are specified in the persistent connections, the carriers for outgoing connections from the topic are respected and those for incoming connections to the topic are ignored).

Listing topics

To get a list of all topics, do:

yarp topic --list

Removing topics

To remove a topic, do:

yarp topic --remove /topic

Using persistent connections from code

Normally, to connect two ports directly in code, you do:

yarp::os::Network yarp;

It is also possible to request connections via topics. If, in one program, we do:

yarp::os::Network yarp;

and in another, we do:

yarp::os::Network yarp;

Then the /camera1 port will end up connecting to the /viewer port whenever both are available.

The "topic://" prefix is not needed if the "/vision" topic has been explicitly created as described in Persistence via topics.

One note of caution: when connecting to a topic, the "connect" command may return before all existing ports connected with that topic becoming connected to each other. If you rely on a connection existing, test for it using either yarp::os::Network::isConnected or yarp::os::Port::getInputCount or yarp::os::Port::getOutputCount.

To connect two ports persistently, without any intermediate topic (only possible with native YARP name service), use code like this:

yarp::os::Network yarp;
style.persistent = true;