Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions ddsrouter_yaml/test/unittest/configuration/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ set(TEST_LIST
max_tx_rate
max_rx_rate
downsampling
xml_participant_endpoint_qos_mode
)

set(TEST_EXTRA_LIBRARIES
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
#include <cpp_utils/testing/gtest_aux.hpp>
#include <gtest/gtest.h>

#include <ddspipe_participants/configuration/XmlParticipantConfiguration.hpp>
#include <ddspipe_yaml/yaml_configuration_tags.hpp>
#include <ddspipe_yaml/testing/generate_yaml.hpp>

Expand Down Expand Up @@ -704,3 +705,94 @@ int main(
::testing::InitGoogleTest(&argc, argv);
return RUN_ALL_TESTS();
}

/**
* Test load of the endpoint QoS mode of an XML participant in the configuration
*
* CASES:
* - Not set -> XML_OVERRIDABLE (default)
* - xml-overridable -> XML_OVERRIDABLE
* - xml-standalone -> XML_STANDALONE
* - Unknown value -> ConfigurationException
* - Set in a participant that is not XML -> ConfigurationException
*/
TEST(YamlReaderConfigurationTest, xml_participant_endpoint_qos_mode)
{
auto load_xml_participant = [](const std::string& endpoint_qos_mode)
{
std::string yml_configuration =
"version: v5.0\n"
"participants:\n"
" - name: P1\n"
" kind: echo\n"
" - name: P2\n"
" kind: xml\n"
" profile: participant_profile\n";

if (!endpoint_qos_mode.empty())
{
yml_configuration += " endpoint-qos-mode: " + endpoint_qos_mode + "\n";
}

ddsrouter::core::DdsRouterConfiguration configuration =
ddsrouter::yaml::YamlReaderConfiguration::load_ddsrouter_configuration(
YAML::Load(yml_configuration));

for (const auto& participant : configuration.participants_configurations)
{
if (participant.first == ddsrouter::core::types::ParticipantKind::xml)
{
auto xml_configuration =
std::dynamic_pointer_cast<ddspipe::participants::XmlParticipantConfiguration>(
participant.second);
EXPECT_NE(nullptr, xml_configuration);
return xml_configuration;
}
}

ADD_FAILURE() << "XML participant not found in the configuration";
return std::shared_ptr<ddspipe::participants::XmlParticipantConfiguration>();
};

// Not set
{
auto xml_configuration = load_xml_participant("");
ASSERT_NE(nullptr, xml_configuration);
EXPECT_EQ(ddspipe::participants::EndpointQoSMode::XML_OVERRIDABLE, xml_configuration->endpoint_qos_mode);
}

// xml-overridable
{
auto xml_configuration = load_xml_participant(ddspipe::yaml::ENDPOINT_QOS_MODE_XML_OVERRIDABLE_TAG);
ASSERT_NE(nullptr, xml_configuration);
EXPECT_EQ(ddspipe::participants::EndpointQoSMode::XML_OVERRIDABLE, xml_configuration->endpoint_qos_mode);
}

// xml-standalone
{
auto xml_configuration = load_xml_participant(ddspipe::yaml::ENDPOINT_QOS_MODE_XML_STANDALONE_TAG);
ASSERT_NE(nullptr, xml_configuration);
EXPECT_EQ(ddspipe::participants::EndpointQoSMode::XML_STANDALONE, xml_configuration->endpoint_qos_mode);
}

// Unknown value
EXPECT_THROW(load_xml_participant("xml-only"), utils::ConfigurationException);

// Set in a participant that is not XML
{
const char* yml_configuration =
R"(
version: v5.0
participants:
- name: P1
kind: echo
- name: P2
kind: local
endpoint-qos-mode: xml-standalone
)";

EXPECT_THROW(
ddsrouter::yaml::YamlReaderConfiguration::load_ddsrouter_configuration(YAML::Load(yml_configuration)),
utils::ConfigurationException);
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,8 @@ std::vector<std::string> invalid_files = {
"./invalid_config_files_router/ds_guid_id_out_of_range.yaml",
"./invalid_config_files_router/ds_participant_no_listening_nor_connection_addresses.yaml",
"./invalid_config_files_router/ds_with_transport.yaml",
"./invalid_config_files_router/endpoint_qos_mode_invalid_value.yaml",
"./invalid_config_files_router/endpoint_qos_mode_non_xml_participant.yaml",
"./invalid_config_files_router/easy_mode_with_whitelist.yaml",
"./invalid_config_files_router/filter_topic_no_name.yaml",
"./invalid_config_files_router/initial_peers_no_addresses.yaml",
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
version: v5.0

participants:

- name: EchoParticipant
kind: echo

- name: xml_participant
kind: xml
profile: custom_participant_configuration
endpoint-qos-mode: xml-only
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
version: v5.0

participants:

- name: EchoParticipant
kind: echo

- name: simple_participant
kind: local
domain: 0
endpoint-qos-mode: xml-standalone
Original file line number Diff line number Diff line change
Expand Up @@ -190,6 +190,8 @@ participants:

profile: custom_participant_configuration # Configure participant with this profile

endpoint-qos-mode: xml-overridable # XML endpoint profiles overridden by the Topic QoS (default)

# Custom generic forwarding route.

routes:
Expand Down
7 changes: 7 additions & 0 deletions docs/rst/notes/forthcoming_version.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,10 @@
Forthcoming Version
###################

Next release will include the following **features**:

* Add the ``endpoint-qos-mode`` tag to the XML Participant to choose how a matching XML endpoint profile is applied
(see :ref:`Endpoint QoS mode <user_manual_participants_xml_endpoint_qos_mode>`).
By default (``xml-overridable``), the profile is used as base and its durability, reliability, ownership and history
are taken from the YAML configuration or from the discovered remote endpoints; ``xml-standalone`` applies the profile
as is.
16 changes: 16 additions & 0 deletions docs/rst/user_manual/configuration.rst
Original file line number Diff line number Diff line change
Expand Up @@ -746,6 +746,7 @@ The tags of a Participant are arranged as follows, and the sections below follow
tls: ... # TLS configuration (see WAN Configuration)

profile: ... # XML profile of an XML Participant
endpoint-qos-mode: ... # How the XML endpoint profiles are applied in an XML Participant

qos: ... # Topic QoS of the Participant

Expand Down Expand Up @@ -1062,6 +1063,19 @@ It will use such profile for configuring the Participant.

profile: participant_custom_configuration

.. _user_manual_configuration_endpoint_qos_mode:

Endpoint QoS mode
-----------------

Tag ``endpoint-qos-mode`` sets how an :ref:`XML Participant <user_manual_participants_xml>` applies the XML endpoint
profiles: ``xml-overridable`` (default) or ``xml-standalone``.
See :ref:`user_manual_participants_xml_endpoint_qos_mode`.

.. code-block:: yaml

endpoint-qos-mode: xml-standalone


.. _user_manual_configuration_participant_topic_qos:

Expand Down Expand Up @@ -1357,6 +1371,8 @@ A complete example of all the configurations described on this page can be found

profile: custom_participant_configuration # Configure participant with this profile

endpoint-qos-mode: xml-overridable # XML endpoint profiles overridden by the Topic QoS (default)

# Custom generic forwarding route.

routes:
Expand Down
44 changes: 35 additions & 9 deletions docs/rst/user_manual/participants/xml.rst
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,7 @@ Endpoint profiles
When the XML Participant creates a :term:`DataWriter` or :term:`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.
By default, ``durability``, ``reliability``, ``ownership`` and ``history`` are still taken from the YAML configuration and from discovery; see :ref:`user_manual_participants_xml_endpoint_qos_mode` to use the profile as is.
If no matching profile exists, the endpoint falls back to default QoS with values derived from the YAML configuration and from discovery.

.. note::
Expand Down Expand Up @@ -130,20 +131,43 @@ Like any other Topic QoS, ``endpoint-profile-name`` can be set in the :ref:`Manu
Since XML profiles are loaded for the whole |ddsrouter| process, this is the way to apply different profiles to the same topic in different XML Participants.
If no profile with that name is loaded, the |ddsrouter| does not look for a profile named after the topic; the endpoint falls back to default QoS instead.

Overriding profile QoS from the YAML configuration
""""""""""""""""""""""""""""""""""""""""""""""""""
.. _user_manual_participants_xml_endpoint_qos_mode:

When a matching XML profile is applied, the following :ref:`Topic QoS <user_manual_configuration_topic_qos>` override the corresponding values from the profile, but only if they are explicitly set in the YAML configuration (in the Manual Topics, the Participant Topic QoS or the Specs Topic QoS):
``durability``, ``reliability``, ``ownership`` and ``history-depth``.
Every other field keeps the value from the XML profile.
Endpoint QoS mode
"""""""""""""""""

QoS values that the |ddsrouter| learns from remote endpoints during discovery never override the XML profile.
Fields that are set neither in the XML profile nor in the YAML configuration therefore take the |fastdds| default values (e.g. ``KEEP_LAST`` history with depth ``1``), instead of being adapted to the discovered endpoints.
The ``endpoint-qos-mode`` tag of the XML Participant sets how a matching XML endpoint profile is applied:

.. list-table::
:header-rows: 1

* - Value
- Behavior

* - ``xml-overridable`` (default)
- The XML profile is used as base.
``durability``, ``reliability``, ``ownership`` and ``history`` are taken from the :ref:`Topic QoS <user_manual_configuration_topic_qos>`, with priority:
YAML configuration (Manual Topics, Participant Topic QoS or Specs Topic QoS) > QoS discovered from the remote endpoints > |ddsrouter| defaults.
Every other policy keeps the value of the XML profile.

* - ``xml-standalone``
- The XML profile is used as is.
Neither the YAML configuration nor the discovered QoS override it.

When no profile is found, the endpoint takes ``durability``, ``reliability``, ``ownership`` and ``history`` from the Topic QoS in both modes.
The ``endpoint-qos-mode`` tag is only accepted by XML Participants.

.. code-block:: yaml

- name: xml_participant
kind: xml
profile: custom_participant_configuration
endpoint-qos-mode: xml-standalone # Use the XML endpoint profiles as is

.. warning::

Setting ``history-depth`` in the Specs Topic QoS overrides the history of every matching XML profile, even when it is set to its default value of ``5000``.
Likewise, if the remote DataWriters use ``EXCLUSIVE_OWNERSHIP_QOS``, set ``ownership`` either in the XML profile or in the YAML configuration, otherwise the DataReaders of the XML Participant will not match them.
With ``xml-standalone``, the endpoints of the XML Participant do not adapt to the QoS of the remote endpoints.
Make sure the XML profiles are compatible with them; e.g. if the remote DataWriters use ``EXCLUSIVE_OWNERSHIP_QOS``, set it in the ``data_writer`` and ``data_reader`` profiles, otherwise the endpoints of the XML Participant will not match them.


Repeater
Expand All @@ -166,3 +190,5 @@ Use |fastdds| or |ddsrouter| support to load XML configuration files as explaine
kind: xml

profile: custom_participant_configuration # Configure participant with this profile

endpoint-qos-mode: xml-overridable # XML endpoint profiles overridden by the Topic QoS (default)
27 changes: 27 additions & 0 deletions resources/configurations/ddsrouter_config_schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -481,6 +481,13 @@
},
"profile":{
"type":"string"
},
"endpoint-qos-mode":{
"type":"string",
"enum":[
"xml-overridable",
"xml-standalone"
]
}
},
"required":[
Expand Down Expand Up @@ -559,6 +566,11 @@
"profile":{
"not":{

}
},
"endpoint-qos-mode":{
"not":{

}
}
}
Expand Down Expand Up @@ -623,6 +635,11 @@
"profile":{
"not":{

}
},
"endpoint-qos-mode":{
"not":{

}
}
}
Expand Down Expand Up @@ -714,6 +731,11 @@
"profile":{
"not":{

}
},
"endpoint-qos-mode":{
"not":{

}
}
}
Expand Down Expand Up @@ -790,6 +812,11 @@
"profile":{
"not":{

}
},
"endpoint-qos-mode":{
"not":{

}
}
}
Expand Down
Loading