| 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. |
| 2 | |
| 3 | == Overview == |
| 4 | |
| 5 | Both orocos.rb and the supervision can automatically use the POSIX MQueues. |
| 6 | |
| 7 | 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: |
| 8 | |
| 9 | * specify a maximum size for them in the orogen spec and/or inside the ruby script and/or in side the supervision models |
| 10 | * 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. |
| 11 | |
| 12 | == Turning it ON == |
| 13 | |
| 14 | Just do |
| 15 | |
| 16 | {{{ |
| 17 | Orocos::MQueue.auto = true |
| 18 | }}} |
| 19 | |
| 20 | orocos.rb will then use MQueues if they are supported on your system (built in the RTT) |
| 21 | |
| 22 | == Setup using maximum size specification == |
| 23 | * '''at the type level''', a maximum size can be declared globally for a type |
| 24 | |
| 25 | {{{ |
| 26 | Orocos.max_sizes '/base/samples/RigidBodyState', 'sourceFrame' => 20, 'targetFrame' => 20 |
| 27 | }}} |
| 28 | |
| 29 | This can be used in orogen files, orocos.rb scripts and supervision scripts |
| 30 | |
| 31 | * '''at the task model level''', the maximum size can be specified with a max_sizes declaration on ports, for instance: |
| 32 | |
| 33 | {{{ |
| 34 | name 'hokuyo' |
| 35 | task_context 'Task' do |
| 36 | output_port('scan_samples', '/base/samples/LaserScan'). |
| 37 | max_sizes('ranges' => 2000) |
| 38 | end |
| 39 | }}} |
| 40 | |
| 41 | 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. |
| 42 | |
| 43 | It can be used in orogen files |
| 44 | |
| 45 | * '''at the task level''', the max size can be set on ports themselves |
| 46 | |
| 47 | {{{ |
| 48 | task = Orocos::TaskContext.get 'hokuyo' |
| 49 | task.scan_samples.max_sizes('ranges' => 1000) |
| 50 | }}} |
| 51 | |
| 52 | * Finally, the supervision has no additional means. One has to use the previous means |
| 53 | |
| 54 | For instance: |
| 55 | {{{ |
| 56 | class Hokuyo::Task |
| 57 | orogen_model.scan_samples.max_sizes('ranges' => 100) |
| 58 | |
| 59 | def configure |
| 60 | super |
| 61 | orogen_task.scan_samples.max_sizes('ranges' => 10) |
| 62 | end |
| 63 | end |
| 64 | }}} |
| 65 | |
| 66 | == Relying on the tasks to call setDataSample == |
| 67 | |
| 68 | 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. |
| 69 | |
| 70 | If you want to use it, do |
| 71 | |
| 72 | {{{ |
| 73 | Orocos::MQueue.auto_sizes = false |
| 74 | Orocos::MQueue.validate_sizes = false |
| 75 | }}} |
| 76 | |
| 77 | == Fallback to CORBA == |
| 78 | |
| 79 | If a MQ connection fails to be created, orocos.rb will fallback to using a CORBA connection and issue a warning. |
| 80 | |
| 81 | This behaviour can be turned OFF with |
| 82 | |
| 83 | {{{ |
| 84 | Orocos::MQueue.auto_fallback_to_corba = false |
| 85 | }}} |
| 86 | |