Refs #21313: Add type_propagation property documentation

Signed-off-by: eduponz <eduardoponz@eprosima.com>
eProsima · Jul 24, 2024 · ad6d48c · ad6d48c
1 parent 6206110
commit ad6d48c
Show file tree

Hide file tree

Showing 5 changed files with 128 additions and 6 deletions.
diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp
@@ -954,6 +954,16 @@ void dds_domain_examples()
  "1200");
  //!--
  }
+
+ {
+ // TYPE_PROPAGATION_PROPERTY
+ DomainParticipantQos pqos;
+
+ pqos.properties().properties().emplace_back(
+ "fastdds.type_propagation",
+ "enabled");
+ //!--
+ }
 }
 
 //DOMAINPARTICIPANTLISTENER-DISCOVERY-CALLBACKS

diff --git a/code/XMLTester.xml b/code/XMLTester.xml
@@ -3248,6 +3248,30 @@
 </data_writer>
 <!--><-->
 
+<!-->TYPE_PROPAGATION_PROPERTY<-->
+<!--
+<?xml version="1.0" encoding="UTF-8" ?>
+<dds xmlns="http://www.eprosima.com">
+ <profiles>
+-->
+ <participant profile_name="type_propagation_domainparticipant_xml_profile">
+ <rtps>
+ <propertiesPolicy>
+ <properties>
+ <property>
+ <name>fastdds.type_propagation</name>
+ <value>enable</value>
+ </property>
+ </properties>
+ </propertiesPolicy>
+ </rtps>
+ </participant>
+<!--
+ </profiles>
+</dds>
+-->
+<!--><-->
+
 <!-->FASTDDS_STATISTICS_MODULE<-->
 <participant profile_name="statistics_domainparticipant_conf_xml_profile">
  <rtps>

diff --git a/docs/fastdds/api_reference/spelling_wordlist.txt b/docs/fastdds/api_reference/spelling_wordlist.txt
@@ -4,8 +4,8 @@ addReaderLocator
 addReaderProxy
 addWriterProxy
 allowlist
-AppliedAnnotationPubSubType
 AppliedAnnotationParameterPubSubType
+AppliedAnnotationPubSubType
 AppliedBuiltinMemberAnnotationsPubSubType
 AppliedBuiltinTypeAnnotationsPubSubType
 AppliedVerbatimAnnotationPubSubType
@@ -78,6 +78,7 @@ datareader
 DataReader
 DataReaderListener
 DataReaderQos
+DataRepresentationId
 DataRepresentationQosPolicy
 DataSharingQosPolicy
 datawriter
@@ -124,8 +125,8 @@ Hashid
 heartbeat_period
 heartbeat_response_delay
 HistoryQosPolicy
-InconsistentTopicStatus
 Implementers
+InconsistentTopicStatus
 infos
 initial_acknack_delay
 initial_heartbeat_delay
@@ -258,9 +259,9 @@ Subclassed
 subclasses
 subentities
 subnetwork
-subsequence
 SubscriberListener
 SubscriptionMatchedStatus
+subsequence
 synchronism
 te
 TimeBasedFilterQosPolicy
@@ -301,8 +302,8 @@ untaken
 untyped
 url
 UserAllocatedSequence
-Utils
 utils
+Utils
 wakeup
 wdata
 WLPListener

diff --git a/docs/fastdds/property_policies/non_consolidated_qos.rst b/docs/fastdds/property_policies/non_consolidated_qos.rst
@@ -398,7 +398,7 @@ Setting ``fastdds.max_message_size`` At Participant Level
  :language: c++
  :start-after: // MAX_MESSAGE_SIZE_PROPERTY_PARTICIPANT
  :end-before: //!--
- :dedent: 6
+ :dedent: 8
 
  .. tab:: XML
 
@@ -421,7 +421,7 @@ Setting ``fastdds.max_message_size`` At Writer Level
  :language: c++
  :start-after: // MAX_MESSAGE_SIZE_PROPERTY_WRITER
  :end-before: //!--
- :dedent: 6
+ :dedent: 8
 
  .. tab:: XML
 
@@ -430,3 +430,83 @@ Setting ``fastdds.max_message_size`` At Writer Level
  :start-after: <!-->MAX_MESSAGE_SIZE_PROPERTY_WRITER<-->
  :end-before: <!--><-->
  :lines: 2,4-14
+
+.. _property_type_propagation:
+
+Type Propagation
+^^^^^^^^^^^^^^^^
+
+By default, *Fast DDS* leverages :ref:`xtypes_discovery_matching` both to discover remote types and to propagate local
+ones.
+Type propagation entails both adding meta-information to the EDP messages (see :ref:`disc_phases`) and using a
+dedicated set of builtin endpoints to transmit type definitions between the different |DomainParticipants| in the
+network.
+
+Depending on the application design and deployment, it might be desirable to change the default type propagation
+behavior to save bandwidth and/or resources.
+For this reason, *Fast DDS* |DomainParticipants| can be configured with a property ``fastdds.type_propagation``
+that controls how type information is propagated.
+
+.. list-table::
+ :header-rows: 1
+ :align: left
+
+ * - PropertyPolicyQos name
+ - PropertyPolicyQos value
+ - Default value
+ * - ``"fastdds.type_propagation"``
+ - ``"disabled"`` |br|
+ ``"enabled"`` |br|
+ ``"minimal_bandwidth"`` |br|
+ ``"registration_only"``
+ - ``"enabled"``
+
+The different property values have the following effects on the local |DomainParticipant|:
+
+.. list-table::
+ :header-rows: 1
+ :align: left
+
+ * - Value
+ - ``TypeObject`` registration
+ - Send type information on EDP
+ - Receive type information on EDP
+ - Type lookup service replies
+ * - ``"disabled"``
+ - NO
+ - NO
+ - IGNORED
+ - DISABLED
+ * - ``"enabled"``
+ - COMPLETE and MINIMAL
+ - COMPLETE and MINIMAL
+ - PROCESSED
+ - ENABLED
+ * - ``"minimal_bandwidth"``
+ - MINIMAL only
+ - MINIMAL only
+ - Only MINIMAL PROCESSED
+ - ENABLED
+ * - ``"registration_only"``
+ - COMPLETE and MINIMAL
+ - COMPLETE and MINIMAL
+ - IGNORED
+ - DISABLED
+
+.. tabs::
+
+ .. tab:: C++
+
+ .. literalinclude:: /../code/DDSCodeTester.cpp
+ :language: c++
+ :start-after: // TYPE_PROPAGATION_PROPERTY
+ :end-before: //!--
+ :dedent: 8
+
+ .. tab:: XML
+
+ .. literalinclude:: /../code/XMLTester.xml
+ :language: xml
+ :start-after: <!-->TYPE_PROPAGATION_PROPERTY<-->
+ :end-before: <!--><-->
+ :lines: 2-4,6-16,18-19
diff --git a/docs/fastdds/xtypes/discovery_matching.rst b/docs/fastdds/xtypes/discovery_matching.rst
@@ -67,6 +67,13 @@ The remote data type discovery feature only works if some requisites are met:
 If the prerequisites are not met, endpoint matching relies on type name and topic name in order to match the discovered
 endpoints.
 
+.. _xtypes_discovery_matching_config:
+
+Configuration
+-------------
+
+The level of propagation of local data types can be configured as specified in :ref:`property_type_propagation`.
+
 Remote types discovery example
 ------------------------------