Collaboration diagram for Portmonitors:Modules | |
| Examples | |
| Examples and tutorials about portmonitors. | |
| Available Portmonitors | |
| List of available portmonitors. | |
In short, it is an extended functionality of a port implemented as a new carrier which allows to dynamically load at run–time script (or dynamically linked libraries such as .so/.dll) and plug it into the port of an existing module without changing the code or recompiling it. Using run-time scripts (e.g. Lua/Python) or DLLs we can access and modify the data traveling through the port using a simple API. In this way extra functionalities of a component can be added during application development time and without the need to modify and rebuild the component itself.
You should connect two ports using the YARP 'portmonitor' carrier modifier and explicitly tells the carrier which type of plug-in you are using (lua, python, dll):
$ yarp connect /out /in tcp+recv.portmonitor+type.lua+context.myapp+file.my_lua_script
This rather weird syntax can be read as follow. Connect port /out to /in using the tcp transport protocol. Chain the receiver (recv) side of the port /in to the plugin portmonitor with parameters: type=lua, context=myapp and file=my_lua_script ('.' here can be indeed interpreted as an assignment operator).
This connects '/out' to '/in' using tcp and a portmonitor carrier modifier on the receiver side. Alternatively the script can be plugged into the sender port:
$ yarp connect /out /in tcp+send.portmonitor+type.lua+context.myapp+file.my_lua_script
or a DLL can be loaded instead of the Lua script:
$ yarp connect /out /in tcp+send.portmonitor+type.dll+file.my_dll_file
This feature is still experimental. You can concatenate multiple portmonitors as in this example, which throttles down a connection, and then adds a simulated delay of 500ms. It's importnat to notice the sequence id suffix (1,2,..etc) that has to be applied to both the file and the type label.
$ yarp connect /mysender /myreceiver fast_tcp+send.portmonitor+file.throttleDown+period_ms.100+type.dll+file1.simulated_network_delay+delay_ms.500+type1.dll
In this example, the stats_monitor is used to stream some statistics on the connection.
$ yarp connect /mysender /myreceiver fast_tcp+send.portmonitor+file.throttleDown+period_ms.500+type.dll+file1.stats_monitor+type1.dll
Test setup:
yarp write /mysender --period 0.01 //then type the string `aaaa` yarp read /myreceiver yarp connect /mysender /myreceiver fast_tcp+send.portmonitor+file.throttleDown+period_ms.500+type.dll+file1.stats_monitor+type1.dll yarp read ... /stats_monitor/mysender/myreceiver/stats:o 1782921328.0867476 "/mysender" "/myreceiver" fast_tcp [ok] 32.0 2.0 4bytes*2Hz
Note that the throttleDown is applied before the stats monitor. If the order of the monitors is swapped, then incorrect statics will be displayed, cause they will be computed before the action of the throttleDown.
yarp write /mysender --period 0.01 //then type the string `aaaa` yarp read /myreceiver yarp connect /mysender /myreceiver fast_tcp+send.portmonitor+file1.throttleDown+period_ms.500+type1.dll+file.stats_monitor+type.dll yarp read ... /stats_monitor/mysender/myreceiver/stats:o 1782921466.0506425 "/mysender" "/myreceiver" fast_tcp [ok] 1488.0 93.0 4bytes*~100Hz
A callback function is assigned to each state (except Waiting) which can have a corresponding implementation in the user’s script. Using these callbacks, users have full control over the port’s data and can access it, modify it and decide whether to accept the data or discard it. The Port Monitor starts in the Create state in which ‘PortMonitor.create’ callback is called. The initialization of the user’s code can be done at this point. Returning a true value means that the user’s initialization was successful and the monitor object is able to start monitoring data from the port. When data arrives to the monitor, ‘PortMonitor.accept’ is called and an instance of YARP ‘Things’ object is passed to the callback function. In this callback, user can access (for reading purposes only) the data, check it and decide whether to accept or discard it. The return value of this function indicates whether the data should be delivered (accepted) or discarded. If the data is accepted, ‘PortMonitor.update’ is called, at which point the user has access to modify the data.
PortMonitor.create = function(options)
...
return true --default
end
PortMonitor.destroy = function()
...
end
PortMonitor.accept = function(thing)
...
return true --default
end
PortMonitor.update = function(thing)
...
return thing
end
PortMonitor.update_reply = function(thing)
...
return thing
end
PortMonitor.setparam = function(param)
...
end
PortMonitor.getparam = function()
...
return param
end
PortMonitor.trig = function()
...
end
A port arbitrator is an extended functionality of an input port which can be configured to arbitrate data from multiple source based on some user–defined constraints.
A port arbitrator consists of multiple port monitors, a set of selection constraints, an event container and a selector block. Port arbitrator extends the port's scripting API for setting constraints and altering events in the container. In fact, when a port monitor is used in an arbitrator, the user's script can access the extended API for arbitration.
A port monitor can be attached to each connection (Ci) going through the port arbitrator. It monitors the data from connection and inserts the corresponding events into a shared container. A port monitor can also remove an event (if previously inserted by itself) from the container. Normally events have infinite life time. This means that they remain valid in the container until they are explicitly removed by the monitor object. An event can also have a specific life time. A time event will be automatically removed from the container when its life time is over. For each connection Ci , there is a selection constraint written in first order logic as a boolean combination of the symbolic events. Upon the reception of data from a connection, the selector evaluates the corresponding constraint and, if satisfied, it allows the data to be delivered to the input port; otherwise the data will be discarded.
Beside the port monitor callbacks, there is a set of auxiliary functions which is offered by the PortMonitor. These auxiliary functions are used for the port arbitration (See An example of using port monitors for arbitrating multiple connections).
See the Examples page