Changes between Version 1 and Version 2 of WikiStart/Toolchain/PosixMQ

Timestamp:

05/10/11 10:49:50 (10 years ago)

Author:

sylvain.joyeux

Comment:

--

WikiStart/Toolchain/PosixMQ

@@ +1 @@
+The POSIX message queues are a mean to transport samples from ports across processes, but locally (i.e. on the same machine). They are a lot more efficient than using CORBA (less copying / marshalling cost) '''and''' they are compatible with hard realtime execution.
+
+== Overview ==
+
+Both orocos.rb and the supervision can automatically use the POSIX MQueues.
+
+The main issue is with variable-sized types,  i.e. types that contain std::vector "somewhere". There are mainly two ways to deal with them:
+
+ * specify a maximum size for them in the orogen spec and/or inside the ruby script and/or in side the supervision models
+ * make sure, in the C++, that the _output_port.setDataSample() method is called '''before''' the startHook() (preference goes for the constructor) with a data sample that is properly sized.
+
+== Turning it ON ==
+
+Just do
+
+{{{
+Orocos::MQueue.auto = true
+}}}
+
+orocos.rb will then use MQueues if they are supported on your system (built in the RTT)
+
+== Setup using maximum size specification ==
+ * '''at the type level''', a maximum size can be declared globally for a type
+
+{{{
+Orocos.max_sizes '/base/samples/RigidBodyState', 'sourceFrame' => 20, 'targetFrame' => 20
+}}}
+
+   This can be used in orogen files, orocos.rb scripts and supervision scripts
+
+ * '''at the task model level''', the maximum size can be specified with a max_sizes declaration on ports, for instance:
+
+{{{
+name 'hokuyo'
+task_context 'Task' do
+  output_port('scan_samples', '/base/samples/LaserScan').
+    max_sizes('ranges' => 2000)
+end
+}}}
+
+   This declares that the 'ranges' field of the laser scans pushed on the scan_samples port is at most 2000 samples big. This specification applies '''on all hokuyo::Task''' that are running on the system.
+
+   It can be used in orogen files
+
+ * '''at the task level''', the max size can be set on ports themselves
+
+{{{
+task = Orocos::TaskContext.get 'hokuyo'
+task.scan_samples.max_sizes('ranges' => 1000)
+}}}
+
+ * Finally, the supervision has no additional means. One has to use the previous means
+
+   For instance:
+{{{
+class Hokuyo::Task
+  orogen_model.scan_samples.max_sizes('ranges' => 100)
+
+  def configure
+    super
+    orogen_task.scan_samples.max_sizes('ranges' => 10)
+  end
+end
+}}}
+
+== Relying on the tasks to call setDataSample ==
+
+This is the "normal" way in RTT. It is not available by default in orocos.rb as we feel that the "size specification" way is more robust.
+
+If you want to use it, do
+
+{{{
+Orocos::MQueue.auto_sizes = false
+Orocos::MQueue.validate_sizes = false
+}}}
+
+== Fallback to CORBA ==
+
+If a MQ connection fails to be created, orocos.rb will fallback to using a CORBA connection and issue a warning.
+
+This behaviour can be turned OFF with
+
+{{{
+Orocos::MQueue.auto_fallback_to_corba = false
+}}}
+
 == System setup ==