diff --git a/docs/rst/notes/forthcoming_version.rst b/docs/rst/notes/forthcoming_version.rst index eac3087ed..89350a22e 100644 --- a/docs/rst/notes/forthcoming_version.rst +++ b/docs/rst/notes/forthcoming_version.rst @@ -6,3 +6,17 @@ Forthcoming Version ################### +This release includes the following **new features**: + +* :ref:`XML Participant ` now supports topic-name endpoint profile lookup: + when creating a :term:`DataWriter` or :term:`DataReader` for a topic, a loaded XML profile whose name + matches the topic name is automatically applied, giving users full control over QoS fields such as + history, memory policy and transport. + A new optional ``xml-override`` tag allows the user to force YAML QoS to take precedence over a matching XML profile. + For more details, see :ref:`user_manual_participants_xml_topic_profiles`. + +This release includes the following **documentation updates**: + +* Document topic-name endpoint profile lookup for the :ref:`XML Participant `, + including QoS fields always enforced by the *DDS Router* regardless of the profile. +* Add *Endpoint Profiles* section to the :ref:`user_manual_configuration` page. \ No newline at end of file diff --git a/docs/rst/user_manual/configuration.rst b/docs/rst/user_manual/configuration.rst index 55ddce904..c9277c868 100644 --- a/docs/rst/user_manual/configuration.rst +++ b/docs/rst/user_manual/configuration.rst @@ -90,6 +90,15 @@ Under the **optional** tag ``raw``, an XML configuration (with the same format a These QoS should be configured by the user explicitly. Check :ref:`user_manual_participants_xml_profiles`. +Endpoint profiles +----------------- + +Profiles named after a topic are automatically applied to :term:`DataWriter` and :term:`DataReader` endpoints +when they are created for that topic by an :ref:`XML Participant `. +By default, when a matching profile is found, the YAML QoS configuration is ignored for that endpoint (XML takes priority). +This behaviour can be changed via the xml-override tag on the participant. +For more details, see :ref:`user_manual_participants_xml_topic_profiles`. + Topics Configuration ==================== diff --git a/docs/rst/user_manual/participants/xml.rst b/docs/rst/user_manual/participants/xml.rst index 3db951401..ff9ea89ee 100644 --- a/docs/rst/user_manual/participants/xml.rst +++ b/docs/rst/user_manual/participants/xml.rst @@ -74,6 +74,56 @@ Notice that not setting such QoS will not affect the correct functionality of th +.. _user_manual_participants_xml_topic_profiles: + +Topic-name endpoint profile lookup +----------------------------------- +When the XML Participant creates a DataWriter or DataReader for a topic, it looks for a loaded XML profile +whose name matches the topic name. +If a matching profile is found, the endpoint is configured using that profile's QoS, giving the user full +control over fields such as history, memory policy, transport, etc. +If no matching profile exists, the endpoint falls back to default QoS with values derived from the YAML configuration. + +By default, when a matching XML profile is found, the YAML QoS configuration is ignored for that endpoint. +This behaviour can be changed by setting the xml-override tag to true in the participant configuration. +When enabled, the YAML QoS values (durability, reliability, ownership, history) will override those from the XML profile. + +.. note:: + + Certain QoS are always enforced by the |ddsrouter| regardless of the XML profile or the ``xml-override`` setting: + deadline on DataWriters (set to minimum so it matches any reader), + ``autodispose_unregistered_instances`` on DataWriters (set to ``false`` to preserve dispose/unregister forwarding semantics), + and ``expects_inline_qos`` on DataReaders for keyed topics. + +The following example loads a profile named ``my_topic`` that will be automatically applied when creating +endpoints for a topic of that name: + + +**YAML** + +.. code-block:: yaml + + - name: xml_participant + kind: xml + xml-override: true + + +**XML** + +.. code-block:: xml + + + + + DYNAMIC + + + DYNAMIC + + + + + Repeater --------