From 770551de8a797e4844a50f047c2dd949204bcd79 Mon Sep 17 00:00:00 2001 From: Robert Haschke Date: Thu, 9 Oct 2014 22:36:26 +0200 Subject: [PATCH] added some more documentation on converters - explain difference between wire-type and wire-schema - explain disambiguation strategy - point out ConverterSelectionStrategy classes --- examples-converters.rst | 41 ++++++++++++++++++++++++++++++++++++----- specification-config.rst | 2 +- specification.rst | 1 + 3 files changed, 38 insertions(+), 6 deletions(-) diff --git a/examples-converters.rst b/examples-converters.rst index 24f0b4b..2f0a1b9 100644 --- a/examples-converters.rst +++ b/examples-converters.rst @@ -13,9 +13,16 @@ In principle, projects using |project| can exchange data of arbitrary types. However, in order to send and receive custom :term:`data types `, |project| has to know how to serialize and deserialize data of these types. This task is performed by :term:`converters -`. :term:`Converters ` are maintained in a -repository at runtime. New :term:`converters ` can be -registered to add support for new :term:`data types `. +`, which transform domain-specific data to a specific +:term:`wire type`. The :term:`wire type` is the language-specific +data holder (typically a string type) passed to the underlying +:term:`transport` mechanism. + +Each converter encodes the payload using a specific :term:`wire schema`, that describes the data +encoding scheme on the wire. In order to successfully receive events with a specific :term:`wire +schema`, appropriate converters need to be available at runtime. While there exist converters for +some basic data :ref:`types `, you need to register the converters for your own +domain-specific :term:`data types ` by yourself. .. _tutorial-converters-register: @@ -30,8 +37,10 @@ obtained. The following example demonstrates this. :term:`Converters ` have to be registered before :term:`participants ` are created. Otherwise, the - :term:`participants ` can still be created, but do not - use the desired :term:`converters `. + :term:`participants ` can still be created, but will not + use the desired :term:`converters `. Even worse, receiving + an event of a non-registered :term:`wire schema` will abort + your application with a :term:`transport` exception. .. container:: converter-registration-multi @@ -115,3 +124,25 @@ obtained. The following example demonstrates this. :end-before: mark-end::body :emphasize-lines: 1 :linenos: + +Disambiguation +============== + +There could be multiple converters encoding to the same :term:`wire schema`. For example, there +could be a common :term:`wire schema` to encode image data, but different domain image types like +OpenCV's or ICL's image classes. In this case, there would be a unique converter for each specific +domain type. In order to resolve ambiguities when handling with different domain types within the +same system, you can :ref:`configure ` your choice under the +configuration section .converter. as = pairs. + +Converter Selection Strategy +============================ + +When you create a new :term:`participant` with the default :cpp:class:`rsb::ParticipantConfig`, it +will configure all its transports using an unambiguous converter selection strategy (implemented by +:cpp:class:`rsb::converter::UnambiguousConverterMap`) evaluating the configuration options described +above. However, you can also replace this default +:cpp:class:`rsb::converter::ConverterSelectionStrategy`, by another one, first modifying the +:cpp:class:`rsb::ParticipantConfig`. The selection strategy is stored in the "converters" option of +the :cpp:class:`ParticipantConfig` :term:`transport` . Note, that each :term:`transport` could use +its own selection strategy. diff --git a/specification-config.rst b/specification-config.rst index 9301cb2..6383d87 100644 --- a/specification-config.rst +++ b/specification-config.rst @@ -10,7 +10,7 @@ principles: * The configuration mechanism works identically across implementation languages -* We cannot (and do not want) to handle configuration of individual +* We cannot (and do not want to) handle configuration of individual :term:`participants `: * The configuration mechanism is intended to provide process-wide diff --git a/specification.rst b/specification.rst index fe13e95..a0bfe57 100644 --- a/specification.rst +++ b/specification.rst @@ -14,6 +14,7 @@ Concepts: specification-uris specification-config specification-plugin + tutorial-converters .. _specification-transports: -- 1.9.1