| 13 |
13 |
types. However, in order to send and receive custom :term:`data types
|
| 14 |
14 |
<data type>`, |project| has to know how to serialize and deserialize
|
| 15 |
15 |
data of these types. This task is performed by :term:`converters
|
| 16 |
|
<converter>`. :term:`Converters <converter>` are maintained in a
|
| 17 |
|
repository at runtime. New :term:`converters <converter>` can be
|
| 18 |
|
registered to add support for new :term:`data types <data type>`.
|
|
16 |
<converter>`, which transform domain-specific data to a specific
|
|
17 |
:term:`wire type`. The :term:`wire type` is the language-specific
|
|
18 |
data holder (typically a string type) passed to the underlying
|
|
19 |
:term:`transport` mechanism.
|
|
20 |
|
|
21 |
Each converter encodes the payload using a specific :term:`wire schema`, that describes the data
|
|
22 |
encoding scheme on the wire. In order to successfully receive events with a specific :term:`wire
|
|
23 |
schema`, appropriate converters need to be available at runtime. While there exist converters for
|
|
24 |
some basic data :ref:`types <types>`, you need to register the converters for your own
|
|
25 |
domain-specific :term:`data types <data type>` by yourself.
|
| 19 |
26 |
|
| 20 |
27 |
.. _tutorial-converters-register:
|
| 21 |
28 |
|
| ... | ... | |
| 30 |
37 |
|
| 31 |
38 |
:term:`Converters <converter>` have to be registered before
|
| 32 |
39 |
:term:`participants <participant>` are created. Otherwise, the
|
| 33 |
|
:term:`participants <participant>` can still be created, but do not
|
| 34 |
|
use the desired :term:`converters <converter>`.
|
|
40 |
:term:`participants <participant>` can still be created, but will not
|
|
41 |
use the desired :term:`converters <converter>`. Even worse, receiving
|
|
42 |
an event of a non-registered :term:`wire schema` will abort
|
|
43 |
your application with a :term:`transport` exception.
|
| 35 |
44 |
|
| 36 |
45 |
.. container:: converter-registration-multi
|
| 37 |
46 |
|
| ... | ... | |
| 115 |
124 |
:end-before: mark-end::body
|
| 116 |
125 |
:emphasize-lines: 1
|
| 117 |
126 |
:linenos:
|
|
127 |
|
|
128 |
Disambiguation
|
|
129 |
==============
|
|
130 |
|
|
131 |
There could be multiple converters encoding to the same :term:`wire schema`. For example, there
|
|
132 |
could be a common :term:`wire schema` to encode image data, but different domain image types like
|
|
133 |
OpenCV's or ICL's image classes. In this case, there would be a unique converter for each specific
|
|
134 |
domain type. In order to resolve ambiguities when handling with different domain types within the
|
|
135 |
same system, you can :ref:`configure <specification-config-files>` your choice under the
|
|
136 |
configuration section <transport>.converter.<language> as <wire-schema> = <data type> pairs.
|
|
137 |
|
|
138 |
Converter Selection Strategy
|
|
139 |
============================
|
|
140 |
|
|
141 |
When you create a new :term:`participant` with the default :cpp:class:`rsb::ParticipantConfig`, it
|
|
142 |
will configure all its transports using an unambiguous converter selection strategy (implemented by
|
|
143 |
:cpp:class:`rsb::converter::UnambiguousConverterMap`) evaluating the configuration options described
|
|
144 |
above. However, you can also replace this default
|
|
145 |
:cpp:class:`rsb::converter::ConverterSelectionStrategy`, by another one, first modifying the
|
|
146 |
:cpp:class:`rsb::ParticipantConfig`. The selection strategy is stored in the "converters" option of
|
|
147 |
the :cpp:class:`ParticipantConfig` :term:`transport` . Note, that each :term:`transport` could use
|
|
148 |
its own selection strategy.
|