From 21e160931f88a4074166813b75fe26e429d6e58e Mon Sep 17 00:00:00 2001 From: Zakaria Talbi Lalmi Date: Tue, 26 May 2026 11:52:03 +0200 Subject: [PATCH 1/2] Documented changes for Topic Profile Lookup Signed-off-by: Zakaria Talbi Lalmi --- docs/rst/notes/forthcoming_version.rst | 14 +++++++ docs/rst/user_manual/configuration.rst | 9 ++++ docs/rst/user_manual/participants/xml.rst | 50 +++++++++++++++++++++++ 3 files changed, 73 insertions(+) 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 -------- From 9fad2d5a7f1699013c93d9e3bd7cc8d7f31267db Mon Sep 17 00:00:00 2001 From: Zakaria Talbi Lalmi Date: Thu, 9 Jul 2026 12:41:53 +0200 Subject: [PATCH 2/2] Updated docs changes to include the latest functionality changes Signed-off-by: Zakaria Talbi Lalmi --- docs/rst/notes/forthcoming_version.rst | 6 ++- docs/rst/spelling_wordlist.txt | 1 + docs/rst/user_manual/configuration.rst | 7 ++- docs/rst/user_manual/participants/xml.rst | 56 +++++++++++++++-------- 4 files changed, 46 insertions(+), 24 deletions(-) diff --git a/docs/rst/notes/forthcoming_version.rst b/docs/rst/notes/forthcoming_version.rst index 89350a22e..8ecc0ed13 100644 --- a/docs/rst/notes/forthcoming_version.rst +++ b/docs/rst/notes/forthcoming_version.rst @@ -12,11 +12,13 @@ This release includes the following **new features**: 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. + A specific profile can also be selected per topic via the new ``endpoint-profile-name`` tag. + A new optional ``endpoint-qos-mode`` participant tag controls whether YAML QoS overrides the matching + XML profile (``xml-overridable``, default) or the profile is applied verbatim (``xml-standalone``). 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 +* Add *Endpoint Profiles* section to the :ref:`user_manual_configuration` page. diff --git a/docs/rst/spelling_wordlist.txt b/docs/rst/spelling_wordlist.txt index b811c937f..4f047921c 100644 --- a/docs/rst/spelling_wordlist.txt +++ b/docs/rst/spelling_wordlist.txt @@ -43,6 +43,7 @@ Requiredness runtime scalable Tsan +unregister utils validator Vulcanexus diff --git a/docs/rst/user_manual/configuration.rst b/docs/rst/user_manual/configuration.rst index c9277c868..5be098dba 100644 --- a/docs/rst/user_manual/configuration.rst +++ b/docs/rst/user_manual/configuration.rst @@ -95,8 +95,11 @@ 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. +A specific profile can also be selected per topic via the ``endpoint-profile-name`` tag, instead of relying +on the topic name. +By default, QoS fields explicitly set in the YAML configuration override the matching XML profile's values +(``endpoint-qos-mode: xml-overridable``); this can be changed to ``xml-standalone`` on the participant so the +XML profile is applied verbatim. 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 ff9ea89ee..3b64eb47d 100644 --- a/docs/rst/user_manual/participants/xml.rst +++ b/docs/rst/user_manual/participants/xml.rst @@ -78,19 +78,16 @@ Notice that not setting such QoS will not affect the correct functionality of th 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 +When the XML Participant creates a DataWriter or DataReader for a topic, it looks for a loaded XML ``data_writer`` +or ``data_reader`` profile to configure that endpoint. +By default, the |ddsrouter| looks for a 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 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: + Certain QoS are always enforced by the |ddsrouter| regardless of the XML profile: 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. @@ -98,18 +95,6 @@ When enabled, the YAML QoS values (durability, reliability, ownership, history) 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 @@ -123,6 +108,37 @@ endpoints for a topic of that name: +Selecting a profile explicitly +""""""""""""""""""""""""""""""" + +Instead of relying on the topic name, a specific profile can be selected for a topic with the +``endpoint-profile-name`` tag under that topic's QoS configuration. +When set, the |ddsrouter| looks up the XML profile with that name instead of the topic name: + +.. code-block:: yaml + + topics: + - name: "rt/chatter" + qos: + endpoint-profile-name: "my_reader_profile" + +Overriding profile QoS from the YAML configuration +""""""""""""""""""""""""""""""""""""""""""""""""""" + +When a matching XML profile is applied, the QoS fields explicitly set by the user in the YAML +configuration take precedence over the values in the XML profile. +This behavior is controlled by the ``endpoint-qos-mode`` participant tag, which accepts two values: + +* ``xml-overridable`` *(default)*: the XML profile is applied first, and any QoS field explicitly set in + the YAML configuration overrides the corresponding value from the profile. +* ``xml-standalone``: the XML profile is applied verbatim; YAML QoS does not override it. + +.. code-block:: yaml + + - name: xml_participant + kind: xml + endpoint-qos-mode: xml-standalone + Repeater --------