diff --git a/docs/rst/notes/forthcoming_version.rst b/docs/rst/notes/forthcoming_version.rst index eac3087ed..8ecc0ed13 100644 --- a/docs/rst/notes/forthcoming_version.rst +++ b/docs/rst/notes/forthcoming_version.rst @@ -6,3 +6,19 @@ 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 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. 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 55ddce904..5be098dba 100644 --- a/docs/rst/user_manual/configuration.rst +++ b/docs/rst/user_manual/configuration.rst @@ -90,6 +90,18 @@ 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 `. +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 3db951401..3b64eb47d 100644 --- a/docs/rst/user_manual/participants/xml.rst +++ b/docs/rst/user_manual/participants/xml.rst @@ -74,6 +74,72 @@ 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 ``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. + +.. note:: + + 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. + +The following example loads a profile named ``my_topic`` that will be automatically applied when creating +endpoints for a topic of that name: + +.. code-block:: xml + + + + + DYNAMIC + + + DYNAMIC + + + + +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 --------