.. include:: vars.rst .. _section-CoreConcepts: ************* Core Concepts ************* This section aims to provide a deeper understanding of the |RS| architecture and give you the required insight to configure and use it effectively. You will learn about: - :ref:`Application resource model `: Gives you a full picture of all the elements that compose |RS|, including details about their relationships with the pluggable components and their lifecycle. - :ref:`section-CoreConcepts-BuiltinPlugins`: Describes the builtin pluggable components that are part of the |RS| module. .. - QoS library selection - Logging - Auto-disable Service section .. _section-CoreConcepts-Rm: Resource Model ============== In this section you will learn the details of the |RS| application resource model (see :ref:`section-Arm`). It describes all the different *resource classes*, their functions and responsibilities, and their relationships with other resources. :numref:`FigureRouterResourceModel` shows a high-level view of the main classes that comprise the application resource model. .. figure:: static/RouterResourceModel.svg :alt: |RS| Resource Model :name: FigureRouterResourceModel :align: center :figwidth: 90% |RS| Application Resource Model There are two main logical planes, each addressing orthogonal sets of capabilities: - **Data Plane**: Set of resources associated with data flow, both user data and metadata. A resource in this plane is also known as an *entity*. The data provision and processing is performed using *plugins* (see :ref:`section-sdk` for an overview of the list of available plugins). - **Control Plane**: Set of resources associated with service monitoring and administration. These are the resources in charge of providing monitoring information and run-time administration of the resources from the data plane. An alternative representation of the resource module is shown in :numref:`FigureRouterObjectModel`. .. figure:: static/RouterObjectModel.svg :alt: |RS| Resource Model :name: FigureRouterObjectModel :align: center :figwidth: 100% |RS| Alternative representation of the Application Resource Model The next sections describe each entity with detail. The documentation for each entity will provide: - A Description of the role and responsibility of the entity within |RS|. - The relationship, if any, with plugin components. This part will give you an understanding of how |RS| achieves custom behavior. - A Description of the states an entity can go through. The next sections describe |RS| from a generic point of view, independently of the |ADAPTER| (or any other type of plugin) that is used. To read more about how DDS is integrated with |RS|, please see the (:ref:`section-CoreConcepts-BuiltinPlugins-DdsAdapter`). It's recommended though that you still review the general model for a solid understanding of |RS|. Directory --------- :numref:`TableResourceReference` provides a resource directory with quick links to access different types of information for each resource or entity. .. list-table:: Resource Reference :name: TableResourceReference :widths: 25 25 25 25 :header-rows: 1 :class: longtable * - Resource - Configuration - Administration - Monitoring * - :ref:`section-CoreConcepts-Rm-Service` - :ref:`section-config-routing-service` - :ref:`section-RemoteAdmin-Api-Service` - :ref:`section-Monitoring-Metrics-Service` * - :ref:`section-CoreConcepts-Rm-DomainRoute` - :ref:`section-config-DomainRoute` - :ref:`section-RemoteAdmin-Api-DomainRoute` - :ref:`section-Monitoring-Metrics-DomainRoute` * - :ref:`section-CoreConcepts-Rm-Connection` - :ref:`section-config-DomainRoute` - :ref:`section-RemoteAdmin-Api-Connection` - :ref:`section-Monitoring-Metrics-DomainRoute` * - :ref:`section-CoreConcepts-Rm-Session` - :ref:`section-config-Session` - :ref:`section-RemoteAdmin-Api-Session` - :ref:`section-Monitoring-Metrics-Session` * - :ref:`section-CoreConcepts-Rm-Route` - :ref:`section-config-Route` - :ref:`section-RemoteAdmin-Api-Route` - :ref:`section-Monitoring-Metrics-Route` * - :ref:`section-CoreConcepts-Rm-Input` - :ref:`section-config-StreamPort` - :ref:`section-RemoteAdmin-Api-StreamPort` - :ref:`section-Monitoring-Metrics-StreamPort` * - :ref:`section-CoreConcepts-Rm-Output` - :ref:`section-config-StreamPort` - :ref:`section-RemoteAdmin-Api-StreamPort` - :ref:`section-Monitoring-Metrics-StreamPort` .. _section-CoreConcepts-Rm-Service: Service ------- The |SERVICE| is the top-level resource. The |SERVICE| is the entity that encapsulates all the resources needed for the operation of both the control and data planes. Typically, a |SERVICE| refers to an execution of |RS|. In the control plane, the |SERVICE| is composed of the *Monitoring* and *Administration* resources, which are optionally available sub-services. These components are described in :ref:`section-Monitoring` and :ref:`section-Admin`, respectively. In the data plane, the |SERVICE| is composed of a collection of user plugins instances and a collection of |DOMAINROUTEs|. .. _section-CoreConcepts-Rm-Service-plugins: Plugin Interaction ^^^^^^^^^^^^^^^^^^ The |SERVICE| is responsible for loading and owning any of the *plugins* that you can provide through the Software Development Kit (see :ref:`section-sdk`). :numref:`FigureRouterServicePlugins` shows the relationship between the |SERVICE| and the plugin objects. .. figure:: static/RouterServicePlugins.svg :alt: |SERVICE| plugins objects :name: FigureRouterServicePlugins :align: center :figwidth: 70% |RS| composed of different plugins See :ref:`section-Common-PluginManagement` for more information about plugin management. .. _section-CoreConcepts-Rm-Service-states: |SERVICE| States ^^^^^^^^^^^^^^^^ A |SERVICE| can be in one of the states listed in :numref:`TableServiceStates`. .. list-table:: Service States :name: TableServiceStates :widths: 10 50 20 20 :header-rows: 1 :class: longtable * - State - Description - Trigger - Plugin callback * - ``ENABLED`` - A |SERVICE| object has loaded the specified service configuration. Monitoring and Administration services are started if they are enabled in the configuration. - - User runs the |RS| application either using the pre-built executable or through the Service API (see :ref:`section-usage`). - Remote command - N/A * - ``STARTED`` - A |SERVICE| object has created all the underlying resources, including creating and starting all the contained |DOMAINROUTEs|, as specified in the configuration. |br| Additionally, the service discovery thread (SDT) is also started. The SDT sets the context to read the data from the builtin input/output *stream* discovery |SRs| |br| Plugin configurations are validated but the libraries are loaded and instances created lazily when they are first needed. - - User spawns the entity - Remote command - N/A * - ``STOPPED`` - A |SERVICE| object has deleted all the resources created during the start phase: the service discovery thread and |DOMAINROUTEs| are deleted. Additionally, any plugin instances are deleted. - - User deletes the entity - Remote command - - ``AdapterPlugin::`` ``delete`` - ``ProcessorPlugin::`` ``delete`` - ``TransformationPlugin::`` ``delete`` * - ``DISABLED`` - A |SERVICE| object has deleted all the resources created during the enable phase. Entering this state occurs only temporarily while the |SERVICE| object is being deleted. - - User shutdowns the entity - Remote command - N/A .. _section-CoreConcepts-Rm-DomainRoute: DomainRoute ----------- A |DOMAINROUTE| defines a collection of independent data domains (such as DDS, MQTT, AMQP, etc.), each modeled as a |CONNECTION|. It's also composed of a collection of |SESSIONs|. .. _section-CoreConcepts-Rm-DomainRoute-States: |DOMAINROUTE_HEADING| States ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A |DOMAINROUTE| can be in one of the states listed in :numref:`TableDomainRouteStates`. .. list-table:: |DOMAINROUTE| states :name: TableDomainRouteStates :widths: 10 50 20 20 :header-rows: 1 :class: longtable * - State - Description - Trigger - Plugin callback * - ``ENABLED`` - A |DOMAINROUTE| object has created all the underlying |CONNECTIONs| and |SESSIONs| as indicated in the configuration. - - Service starts (:ref:`section-CoreConcepts-Rm-Service-states`) - Remote command - N/A * - ``STARTED`` - A |DOMAINROUTE| object has enabled all the contained |CONNECTIONs| and started all the contained |SESSIONs|. The |DOMAINROUTE| is attached to the service discovery thread and may start processing *stream* discovery data. - - Service starts (:ref:`section-CoreConcepts-Rm-Service-states`) - Remote command - N/A * - ``STOPPED`` - A |DOMAINROUTE| object has stopped all |SESSIONs| and disabled all the |CONNECTIONs|. The |DOMAINROUTE| is detached from the service discovery thread. - - Service stops (:ref:`section-CoreConcepts-Rm-Service-states`) - Remote command - N/A * - ``DISABLED`` - A |DOMAINROUTE| object has deleted all the underlying |CONNECTIONs|. Entering this state occurs only temporarily while the |DOMAINROUTE| object is being deleted. - - Stop |DR| - N/A .. _section-CoreConcepts-Rm-Connection: Connection ---------- A |CONNECTION| defines an access point to a specific data domain. The access to a data domain is provided through an instance of an |ADAPTER| plugin, which is specified in the configuration (See :numref:`TableConnectionTag` and :numref:`TableParticipantTag`). For example, the associated |ADAPTER| plugin implementation could provide a connection to an HTTP Server through an HTTP Client, or a logical connection to a DDS Domain through a |DP|. The |CONNECTION| is also responsible for tracking all the *stream* information that is provided by the underlying *input and output stream discovery* |SRs|. The |CONNECTION| gets notified about new or disposed *streams* and propagates this information downstream to the |ROUTEs| and |ARs|, which will process and generate events accordingly. .. note:: A |DP| is a special type of |CONNECTION| that represents an instance of a ``DdsConnection``. For this case, special custom tags are available that facilitate configuring the ``DdsConnection``. .. _section-CoreConcepts-Rm-Connection-Plugins: Plugin Interaction ^^^^^^^^^^^^^^^^^^ :numref:`FigureRouterConnectionPlugins` shows the relationship with the plugin objects. A |CONNECTION| shall hold one, and only one, ``adapter::Connection`` object. .. figure:: static/RouterConnectionPlugins.svg :alt: |CONNECTION| plugins objects :name: FigureRouterConnectionPlugins :align: center :figwidth: 70% Relationship of plugins with a |CONNECTION| .. _section-CoreConcepts-Rm-Connection-States: |CONNECTION| States ^^^^^^^^^^^^^^^^^^^ A |CONNECTION| can be in one of the states listed in :numref:`TableConnectionStates`. .. list-table:: |CONNECTION| states :name: TableConnectionStates :widths: 10 50 20 20 :header-rows: 1 :class: longtable * - State - Description - Trigger - Plugin callback * - ``ENABLED`` - A |CONNECTION| object has created the underlying |ADAPTER| connection object. - - |DOMAINROUTE| starts (:ref:`section-CoreConcepts-Rm-DomainRoute-states`) - - ``AdapterPlugin::`` ``new`` (only once for each plugin class) - ``AdapterPlugin::`` ``create_connection`` * - ``DISABLED`` - A |CONNECTION| object has deleted the |ADAPTER| connection object it holds. - - |DOMAINROUTE| stops (:ref:`section-CoreConcepts-Rm-DomainRoute-states`) - ``AdapterPlugin::`` ``delete_connection`` .. _section-CoreConcepts-Rm-Connection-TypeReg: Type Registration ^^^^^^^^^^^^^^^^^ The |CONNECTION| is the entity where *type registration* takes place. A |CONNECTION| keeps a list of registered types, where each entry in the list contains: - **type registered name**: Unique name used to identify and register a concrete type within the |CONNECTION|. - **type representation**: In-memory structure that describes the type itself. The type representation is adapter-dependent and |RS| assumes ``TypeCode`` as default type representation for types. A type is associated with a *stream* and its registration is required in order to create |SRs| and |SWs|. A type can be registered in two ways: - Through *stream* discovery information, provided by the builtin stream discovery |SRs|. On stream discovery, the associated information contains the registered name and the representation for a type. - Through XML |CONNECTION| configuration (see :ref:`section-Config-XmlTypes`). A type definition is provided in XML and the |RS| parser will generate a ``TypeCode`` from it. |CONNECTION| configuration can then reference this XML type definition to register it. .. _section-CoreConcepts-Rm-Session: Session ------- A |SESSION| defines a collection of |ROUTEs| and |ARs|. It also defines a multi-threaded safe context for |ROUTE| event processing. Events from a |ROUTE| are processed sequentially within the same |SESSION|. A |ROUTE| event is processed by a single thread at a time. That is, the same route cannot be processed concurrently. However, within a |SESSION|, different |ROUTEs| that can be processed concurrently, as many as the number of threads available within the |SESSION|. :numref:`FigureRouterSessionThreads` shows the event processing mechanism. Consider a |SESSION| with a pool of ``N`` threads and composed of ``P`` |ROUTEs|. .. figure:: static/RouterSessionThreads.svg :alt: |CONNECTION| plugins objects :name: FigureRouterSessionThreads :align: center :figwidth: 80% Processing mechanism of |ROUTES| within a |SESSION| - |SESSION| threads are idle waiting for |ROUTEs| to become active. An active |ROUTE| is one that has events pending processing. - Once an active |ROUTE| is selected for processing, all the pending events at that time will be consumed sequentially one after the other (see :ref:`section-CoreConcepts-Rm-Route` for information about route processing). To prevent starvation, new events arriving will be deferred for the next selection cycle. - A |SESSION| selects |ROUTEs| for processing in a round-robin fashion, following the same order as they are defined in the |SESSION| configuration. At a maximum only ``N`` |ROUTEs| can be processed concurrently. Remaining active |ROUTEs| will wait until a thread becomes available. :numref:`FigureRouterSessionThreads` shows a |SESSION| concurrently processing ``N`` active |ROUTEs|. Other remaining ``P-N`` |ROUTEs|, such as Route\ :sub:`P`, are active and waiting for a thread to become available; Route\ :sub:`P-1` is not active (no pending events). .. _section-CoreConcepts-Rm-Session-Plugins: Plugin Interaction ^^^^^^^^^^^^^^^^^^ :numref:`FigureRouterSessionPlugins` shows the relationship with the plugin objects. A |SESSION| shall hold one ``adapter::Session`` object for each |CONNECTION| in the parent |DOMAINROUTE|. .. figure:: static/RouterSessionPlugins.svg :alt: |SESSION| plugins objects :name: FigureRouterSessionPlugins :align: center :figwidth: 70% Relationship of plugins with a |SESSION| .. _section-CoreConcepts-Rm-Session-States: |SESSION| States ^^^^^^^^^^^^^^^^ A |SESSION| can be in one of the states listed in :numref:`TableSessionStates`. .. list-table:: |SESSION| states :name: TableSessionStates :widths: 10 50 20 20 :header-rows: 1 :class: longtable * - State - Description - Trigger - Plugin callback * - ``ENABLED`` - A |SESSION| object has created all the underlying ``adapter::Session`` objects. It has also created all the |ARs| and |ROUTEs| that are defined in the configuration. - - |DOMAINROUTE| starts (:ref:`section-CoreConcepts-Rm-DomainRoute-states`) - Remote command - ``Connection::create_session`` * - ``STARTED`` - A |SESSION| object has started the thread pool, and enabled all the underlying |ARs| and |ROUTEs|. In this state, the |SESSION| is actively processing |ROUTE| events. - - |DOMAINROUTE| starts (:ref:`section-CoreConcepts-Rm-DomainRoute-states`) - Remote command - N/A * - ``STOPPED`` - A |SESSION| object has stopped the thread pool, and disabled all the underlying |ARs| and |ROUTEs|. - - |DOMAINROUTE| stops (:ref:`section-CoreConcepts-Rm-DomainRoute-states`) - Remote command - N/A * - ``DISABLED`` - A |SESSION| object has deleted all the ``adapter::Session`` objects it holds. - - |DOMAINROUTE| stops (:ref:`section-CoreConcepts-Rm-DomainRoute-states`) - Remote command - ``Connection::delete_session`` .. _section-CoreConcepts-Rm-Route: Route ----- A |ROUTE| defines a processing unit for data streams. A |ROUTE| is composed of ``N`` |INPUTs| and ``M`` |OUTPUTs|, each referencing any of the |CONNECTIONs| defined as part of the parent |DOMAINROUTE|. A |ROUTE| generates certain events that are processed safely and serially within one of the threads from the parent |SESSION|. |ROUTE| events are processed through a pluggable |PROCESSOR|. .. note:: A |TR| is a special type of |ROUTE|. All its |INPUTs| and |OUTPUTs| are tied to the builtin DDS |ADAPTER|. For this case, special and custom tags are available that facilitate configuring the |TR|. Plugin Interaction ^^^^^^^^^^^^^^^^^^ :numref:`FigureRouterRoutePlugins` shows the relationship with the plugin objects. A |ROUTE| shall hold one |PROCESSOR| object, which will receive the notifications of the events affecting the owner |ROUTE|. .. figure:: static/RouterRoutePlugins.svg :alt: |SESSION| plugins objects :name: FigureRouterRoutePlugins :align: center :figwidth: 70% Relationship of plugins with a |ROUTE| For more information about the |PROCESSOR| behavior and |ROUTE| events, see the main page of API documentation (:ref:`section-sdk`). .. _section-CoreConcepts-Rm-Route-States: |ROUTE| States ^^^^^^^^^^^^^^ A |ROUTE| state machine is shown in :numref:`FigureRouterRouteState`. .. figure:: static/RouterRouteState.svg :alt: |ROUTE| state machine :name: FigureRouterRouteState :align: center :figwidth: 90% |ROUTE| state machine :numref:`TableRouteStates` shows all the states a |ROUTE| can enter. .. list-table:: |ROUTE| states :name: TableRouteStates :widths: 10 50 20 20 :header-rows: 1 :class: longtable * - State - Description - Trigger - Plugin callback * - ``ENABLED`` - A |ROUTE| has created the underlying |PROCESSOR|. The |ROUTE| is attached to the parent |SESSION| and is receiving event notifications. - - |SESSION| starts (:ref:`section-CoreConcepts-Rm-Session-states`) - Remote command - - ``ProcessorPlugin::new`` (only once for each plugin class) - ``ProcessorPlugin::`` ``create_processor`` * - ``DISABLED`` - A |ROUTE| has deleted the underlying |PROCESSOR|. The |ROUTE| is detached from the parent |SESSION| so no events are notified. - - |SESSION| stops (:ref:`section-CoreConcepts-Rm-Session-states`) - Remote command - ``ProcessorPlugin::`` ``delete_processor`` * - ``STARTED`` - A |ROUTE| has enabled all its |INPUTs| and |OUTPUTs|. - - |SESSION| starts (:ref:`section-CoreConcepts-Rm-Session-states`) - Enable |INPUT| (:ref:`section-CoreConcepts-Rm-Input-states`) or |OUTPUT| (:ref:`section-CoreConcepts-Rm-Output-states`) - Remote command - ``Processor::on_route_event`` * - ``STOPPED`` - A |ROUTE| has disabled at least one of its |INPUTs| and |OUTPUTs|. - - |SESSION| stops (:ref:`section-CoreConcepts-Rm-Session-states`) - Disable |INPUT| (:ref:`section-CoreConcepts-Rm-Input-states`) or |OUTPUT| (:ref:`section-CoreConcepts-Rm-Output-states`) - Remote command - ``Processor::on_route_event`` * - ``RUNNING`` - A |ROUTE| is ready to process data stream related events. These include: - ``DATA_ON_INPUTS`` - ``PERIODIC_ACTION`` - - |SESSION| starts (:ref:`section-CoreConcepts-Rm-Session-states`) - Enable |INPUT| (:ref:`section-CoreConcepts-Rm-Input-states`) or |OUTPUT| (:ref:`section-CoreConcepts-Rm-Output-states`) - Remote command - - ``Processor::on_route_event`` - ``StreamReader::read`` - ``StreamReader::return_loan`` - ``Transformation::transform`` - ``Transformation::return_loan`` - ``StreamWriter::write`` * - ``PAUSED`` - A |ROUTE| is temporarily suspending the processing of data stream related events. - - |SESSION| stops - Disable |INPUT| (:ref:`section-CoreConcepts-Rm-Input-states`) or |OUTPUT| (:ref:`section-CoreConcepts-Rm-Output-states`) - Remote command - ``Processor::`` ``on_route_event`` .. _section-CoreConcepts-Rm-AutoRoute: AutoRoute --------- An |AR| represents a factory of single-input single-output |ROUTEs|. An |AR| creates |ROUTEs| based on a *name filter* criteria that matches the name or type of a *stream*. An |AR| creates a |ROUTE| per stream name: .. math:: [S_{m}] where S\ :sub:`m`\ is the name for the *stream* ``m``. The name of the type T\ :sub:`m`\, only plays a role while passing the filter criteria and while creating the generated |ROUTE|'s |INPUT| and |OUTPUT|. This means a *stream* name that is shared by multiple type names won't spawn a new |ROUTE| from an |AR| per type name. Rather it will reuse the first one generated for the shared *stream* name. .. note:: It is not advised to have *streams* share the same name but have different type names when using an |AR|. It can lead to a situation where the |INPUT| and |OUTPUT| discover *streams* with different type names, leading to an incompatible |ROUTE| creation - especially when dealing with the builtin DDS |ADAPTER|. In such a situation it is better to bifurcate the *streams* based on their stream name. In the case of the builtin DDS |ADAPTER|, if the two types under the same topic (stream) name are compatible as per the rules of :link_connext_gsg_ext_types:`Extensible Types <>`, only then will data be successfully routed by the common generated |ROUTE|. The generation of a |ROUTE| occurs only on the event of a newly discovered *stream*. The resulting |ROUTE| has a single |INPUT| and a single |OUTPUT|, both for the same *stream* name and type. The created |ROUTE| executes within the context of the parent |SESSION| of the |AR|. :numref:`FigureRouterAutoRouteMap` illustrates this relationship. .. figure:: static/RouterAutoRouteMap.svg :alt: |AR| as a factory of |ROUTEs| :name: FigureRouterAutoRouteMap :align: center :figwidth: 90% |AR| as a map of |ROUTEs| keyed by stream name The |AR| creates a |ROUTE| only if it has not previously matched S\ :sub:`m`\. |ARs| never delete the created |ROUTE|, regardless of whether the matching *streams* are disposed or not. .. note:: An |ATR| is a special type of |AR| whose |INPUTs| and |OUTPUTs| are tied to the builtin DDS |ADAPTER|. For this case, special and custom tags are available that facilitate configuring the |ATR|. .. _section-CoreConcepts-Rm-AutoRoute-States: |AR| States ^^^^^^^^^^^ An |AR| can be in one of the states listed in :numref:`TableAutoRouteStates`. .. list-table:: |AR| states :name: TableAutoRouteStates :widths: 10 50 20 20 :header-rows: 1 :class: longtable * - State - Description - Trigger - Plugin callback * - ``ENABLED`` - |AR| object is read to start matching *streams* and create |ROUTEs|. Previously discovered streams are matched retroactively. - - |SESSION| starts (:ref:`section-CoreConcepts-Rm-Session-states`) - Remote command - N/A * - ``STARTED`` - This state is equivalent to the ``ENABLED`` state and the transition is automatic upon enabling. This state is added for consistency with the other entities. - - Enable |AR| - N/A * - ``STOPPED`` - This state is equivalent to the ``DISABLED`` state and the transition is automatic upon disabling. This state is added for consistency with the other entities. - - Disable |AR| - N/A * - ``DISABLED`` - |AR| stops matching all newly discovered *streams*. All the |ROUTEs| created from this |AR| are deleted. - - |SESSION| stops (:ref:`section-CoreConcepts-Rm-Session-states`) - N/A .. _section-CoreConcepts-Rm-Input: Input ----- An |INPUT| is responsible for obtaining data associated with a specific *stream* uniquely identified by its name and type. An |INPUT| must reference an existing |CONNECTION| within the parent |DOMAINROUTE|. The referenced |CONNECTION| determines the data domain where the |INPUT| will obtain data. An |INPUT| has scope only within the parent |ROUTE|. It cannot be shared in other |ROUTEs|. If another |ROUTE| requires accessing the same data stream, a new |INPUT| shall be defined within such |ROUTE|. .. _section-CoreConcepts-Rm-Input-Plugins: Plugin Interaction ^^^^^^^^^^^^^^^^^^ :numref:`FigureRouterInputPlugins` shows the relationship with the plugin objects. An |INPUT| shall hold one, and only one, ``adapter::StreamReader`` object. Optionally, an |INPUT| may hold one and only ``transformation::Transformation`` instance, that is applied to the sample stream returned by the ``adapter::StreamReader``. .. figure:: static/RouterInputPlugins.svg :alt: |INPUT| plugins objects :name: FigureRouterInputPlugins :align: center :figwidth: 90% Relationship of plugins with an |INPUT| The |INPUT| obtains data from a domain by calling the ``StreamReader::read`` operation. If a |TRANSF| is present, the ``Transformation::transform`` operation is called right after reading from the |SR|. The ``Transformation::return_loan`` is called when the obtained loaned samples are returned. .. _section-CoreConcepts-Rm-Input-States: |INPUT| States ^^^^^^^^^^^^^^ An |INPUT| can be in one of the states listed in :numref:`TableInputStates`. .. list-table:: |INPUT| states :name: TableInputStates :widths: 10 45 30 15 :header-rows: 1 :class: longtable * - State - Description - Trigger - Plugin callback * - ``ENABLED`` - |INPUT| has created its underlying |SR| and it's ready to read data. - The following two conditions shall be met: |br| - Matching type is available - Creation mode condition becomes true - - ``Connection::`` ``create_stream_reader`` - ``Processor::`` ``on_route_event`` * - ``STARTED`` - This state is equivalent to the ``ENABLED`` state and the transition is automatic upon enabling. This state is added for consistency with the other entities. - - Enable |INPUT| - N/A * - ``STOPPED`` - This state is equivalent to the ``DISABLED`` state and the transition is automatic upon disabling. This state is added for consistency with the other entities. - - Disable |INPUT| - N/A * - ``DISABLED`` - |INPUT| has deleted its underlying |SR| and can no longer read data. - Creation mode condition becomes false - - ``Connection::`` ``delete_stream_reader`` - ``Processor::`` ``on_route_event`` .. _section-CoreConcepts-Rm-Output: Output ------ An |OUTPUT| is responsible for writing data associated with a specific *stream* uniquely identified by its name and type. An |OUTPUT| must reference an existing |CONNECTION| within the parent |DOMAINROUTE|. The referenced |CONNECTION| determines the data domain where the |OUTPUT| will provide data. An |OUTPUT| has scope only within the parent |ROUTE|. It cannot be shared in other |ROUTEs|. If another |ROUTE| requires access to the same data stream, a new |OUTPUT| shall be defined within such |ROUTE|. .. _section-CoreConcepts-Rm-Output-Plugins: Plugin Interaction ^^^^^^^^^^^^^^^^^^ :numref:`FigureRouterOutputPlugins` shows the relationship with the plugin objects. An |OUTPUT| shall hold one, and only one, ``adapter::StreamWriter`` object. Optionally, an |INPUT| may hold one and only ``transformation::Transformation`` instance, that is applied to a sample stream before is passed to the ``adapter::StreamWriter``. .. figure:: static/RouterOutputPlugins.svg :alt: |OUTPUT| plugins objects :name: FigureRouterOutputPlugins :align: center :figwidth: 90% Relationship of plugins with an |OUTPUT| The |OUTPUT| provides the data to a domain by calling the ``StreamWriter::write`` operation. If a |TRANSF| is present, the ``Transformation::transform`` operation is called right before writing on the |SW|, followed by a ``Transformation::return_loan`` right after. .. _section-CoreConcepts-Rm-Output-States: |OUTPUT| States ^^^^^^^^^^^^^^^ An |OUTPUT| can be in one of the states listed in :numref:`TableOutputStates`. .. list-table:: |OUTPUT| states :name: TableOutputStates :widths: 10 45 30 15 :header-rows: 1 :class: longtable * - State - Description - Trigger - Plugin callback * - ``ENABLED`` - |OUTPUT| has created its underlying |SW| and it's ready to write data. - The following two conditions shall be met: |br| - Matching type is available - Creation mode condition becomes true - - ``Connection::`` ``create_stream_writer`` - ``Processor::`` ``on_route_event`` - ``TransformationPlugin::new`` (only once for each plugin class) - ``TransformationPlugin::create_transformation`` * - ``STARTED`` - This state is equivalent to the ``ENABLED`` state and the transition is automatic upon enabling. This state is added for consistency with the other entities. - - Enable |OUTPUT| - N/A * - ``STOPPED`` - This state is equivalent to the ``DISABLED`` state and the transition is automatic upon disabling. This state is added for consistency with the other entities. - - Disable |OUTPUT| - N/A * - ``DISABLED`` - |OUTPUT| has deleted its underlying |SW| and can no longer write data. - Creation mode condition becomes false - - ``Connection::`` ``delete_stream_writer`` - ``TransformationPlugin::delete_transformation`` - ``Processor::`` ``on_route_event`` .. _section-CoreConcepts-BuiltinPlugins: Builtin plugins ================ Builtin plugins come pre-registered in memory within |RS|. Any configurable aspects are available through dedicated special tags for enhanced usability. .. _section-CoreConcepts-BuiltinPlugins-DdsAdapter: DDS Adapter ----------- This is an |ADAPTER| implementation that provides access to DDS domains. :numref:`FigureRouterDdsAdapter` shows the architecture of the DDS |ADAPTER|. .. figure:: static/RouterDdsAdapter.svg :alt: DDS |ADAPTER| architecture :name: FigureRouterDdsAdapter :align: center :figwidth: 80% DDS |ADAPTER| architecture Most of the use cases expect to have DDS as the main data domain in the user data plane. For this reason, you will find that |RS| specializes some entities so that they are directly associated with DDS. These entities are: - *Participant* - *AutoTopicRoute* - *TopicRoute* - *DdsInput* - *DdsOutput* These entities are equivalent to the generic entities shown in :numref:`FigureRouterResourceModel` except that the |ADAPTER| entity they enclose is created from the builtin DDS |ADAPTER| (:ref:`section-CoreConcepts-BuiltinPlugins-DdsAdapter`). :numref:`FigureRouterDdsResourceModel` shows the DDS specialization of the generic resource model. .. figure:: static/RouterDdsResourceModel.svg :alt: |RS| Resource Model :name: FigureRouterDdsResourceModel :align: center :figwidth: 98% |RS| DDS Application Resource Model DDS AdapterPlugin ^^^^^^^^^^^^^^^^^ The ``DdsAdapter`` is an implementation of the |ADAPTER| interface. It's responsible for creating DDS |CONNECTIONs|. .. list-table:: DDS |ADAPTER| :name: TableRouterDdsAdapterPlugin :widths: 60 40 :header-rows: 1 :class: longtable * - Mapping - Configuration Tag * - It uses the *DomainParticipantFactory* to create the participants needed by each DDS |CONNECTION| - ```` (only in ``USER_QOS_PROFILES.xml``) DDS Connection ^^^^^^^^^^^^^^ The ``DdsConnection`` is an implementation of the |CONNECTIONs| interface. It is responsible for joining to a specific DDS Domain. It's also the factory for creating DDS |SESSIONS|, |SRS| and |SWS|. The ``DdsConnection`` relies on the ``DdsAdapter`` for creating |DPs|. This class creates the |TOPICs| associated with the |DRs| and |DWs| it also creates. .. list-table:: DDS |CONNECTION| :name: TableRouterDdsConnection :widths: 60 40 :header-rows: 1 :class: longtable * - Mapping - Configuration Tag * - Composed of only one |DP| - ``/`` (see :numref:`TableParticipantTag`) DDS Session ^^^^^^^^^^^ The ``DdsSession`` is an implementation of the |SESSION| interface. It's responsible for creating |SUBs| and |PUBs|. .. list-table:: DDS |SESSION| :name: TableRouterDdsSession :widths: 60 40 :header-rows: 1 :class: longtable * - Mapping - Configuration Tag * - Composed of only one |PUB| and one |SUB| - ``/`` and ``/`` (see :numref:`TableSessionTag`) Note that, as explained in :ref:`section-CoreConcepts-Rm-Session-Plugins`, a new ``DdsSession`` object is instantiated for each pair ```` and ```` element within the parent |DOMAINROUTE|. DDS StreamReader ^^^^^^^^^^^^^^^^ The ``DdsStreamReader`` is an implementation of the |SR| interface. It's responsible for reading data from a |TOPIC| and providing it to the parent |ROUTE|, which is in charge of processing it through the installed |PROCESSOR|. .. list-table:: DDS |SR| :name: TableRouterDdsStreamReader :widths: 60 40 :header-rows: 1 :class: longtable * - Mapping - Configuration Tag * - Composed of only one |DR| - ``/`` and ``/`` (see :numref:`TableInputOutputTopicRouteTags`) The referenced DDS |CONNECTION| and parent ```` determines from which |DP| and |SUB| the |DR| is created. The configuration of the |INPUT| owning the |SR| indicates: - The referenced DDS |CONNECTION| that contains the |DP| - The parent ````, which along with the referenced |CONNECTION|, determines which ``DdsSession`` and hence |SUB| is used to create the |DR|. - The name of the |TOPIC| in the domain of the |DP|. DDS StreamWriter ^^^^^^^^^^^^^^^^ The ``DdsStreamWriter`` is an implementation of the |SW| interface. It's responsible for writing data to a |TOPIC|. The data is provided by the parent |ROUTE| through the installed |PROCESSOR|. .. list-table:: DDS |SW| :name: TableRouterDdsStreamWriter :widths: 60 40 :header-rows: 1 :class: longtable * - Mapping - Configuration Tag * - Composed of only one |DW| - ``/`` and ``/`` (see :numref:`TableInputOutputTopicRouteTags`) The referenced DDS |CONNECTION| and parent ```` determines from which |DP| and |PUB| the |DW| is created. The configuration of the |OUTPUT| owning the |SW| indicates: - The referenced DDS |CONNECTION| that contains the |DP| - The parent ````, which along with the referenced |CONNECTION| determines which ``DdsSession`` and hence |PUB| is used to create the |DW|. - The name of the |TOPIC| in the domain of the |DP|. .. _section-CoreConcepts-BuiltinPlugins-ForwardingProcessor: Forwarding Processor -------------------- This is a |PROCESSOR| implementation that forwards samples within a |ROUTE|. The plugin registered name is reserved and has the value ``rti.routingservice.RoutingProcessor``. The functions of the builtin forwarding |PROCESSOR| are: - Forwarding all the *live* data samples received from each |INPUT| to each |OUTPUT|. - Proxying the *TopicQueries* received by the ``DdsStreamWriter``, making sure all the *TopicQuery* data samples received from each |INPUT| are sent to the corresponding |OUTPUTs| and final destination |DRs|. (see :ref:`section-TopicQuerySupport-Propagation`). These functions are executed under the notification of the ``DATA_ON_INPUTS`` and ``PERODIC_ACTION`` events. The builtin forwarding |PROCESSOR| is set by default in all |ARs| and |ROUTEs|. Note that if you install your own |PROCESSOR| implementation, you will override the functionality described above. In this case, even if the dedicated configuration tags are specified (such as ````), they will not have any effect.