DISCOVERY_CONFIG QosPolicy (DDS Extension)

44.3 DISCOVERY_CONFIG QosPolicy (DDS Extension)

The DISCOVERY_CONFIG QosPolicy is used to tune the discovery process. It controls how often to send discovery packets, how to determine when participants are alive or dead, and resources used by the discovery mechanism.

The amount of network traffic required by the discovery process can vary widely based on how your application has chosen to configure the middleware's network addressing (unicast vs. multicast, multicast TTL, etc.), the size of the system, whether all applications are started at the same time or whether start times are staggered, and other factors. Your application can use this policy to make trade-offs between discovery completion time and network bandwidth utilization. In addition, you can introduce random back-off periods into the discovery process to decrease the probability of network contention when many applications start simultaneously.

This QosPolicy includes the members in Table 44.3 DDS_DiscoveryConfigQosPolicy. Many of these members are described in 22. Discovery Overview. For defaults and valid ranges, please refer to the API Reference HTML documentation.

Table 44.3 DDS_DiscoveryConfigQosPolicy
Type	Field Name	Description
DDS_Duration_t	participant_liveliness_lease_duration	The time period after which other DomainParticipants can consider this one dead if they do not receive a liveliness packet from this DomainParticipant.
DDS_Duration_t	participant_liveliness_ assert_period	The period of time at which this DomainParticipant will send out packets asserting that it is alive. When using SPDP (22.1 Simple Participant Discovery), the message sent at this period serves two purposes: to assert a participant’s liveliness and to announce a participant to potential new peers. These messages are full participant announcements containing all information needed for participant discovery to complete. When using SPDP2 (22.2 (Experimental) Simple Participant Discovery 2.0), this field only configures the period at which small liveliness messages are sent. These messages contain only the information needed for a participant to identify another remote participant. The participant_announcement_period configures how often participant announcement messages are sent for the purpose of discovering new peers.
DDS_RemoteParticipantPurgeKind	remote_participant_purge_kind	Controls the DomainParticipant's behavior for purging records of remote participants (and their contained entities) with which discovery communication has been lost. See 44.3.2 Controlling Purging of Remote Participants.
DDS_Duration_t	max_liveliness_loss_detection_period	The maximum amount of time between when a remote entity stops maintaining its liveliness and when the matched local entity realizes that fact.
DDS_Long	initial_participant_announcements	Sets how many initial participant announcements the DomainParticipant will send to all initial peers when it is first enabled. They are sent at a random period between min_initial_participant_announcement_period and max_initial_participant_announcement_period.
DDS_Long	new_remote_participant_announcements	Sets how many participant announcements the DomainParticipant will send only to newly discovered participants after the initial_participant_announcements have completed. They are sent at a random period between min_initial_participant_announcement_period and max_initial_participant_announcement_period.
DDS_Duration_t	min_initial_participant_announcement_period	Sets the minimum and maximum times between participant announcements when sending initial_participant_announcements or new_remote_participant_announcements. These messages are sent with a period between them that is a random duration between min_ initial_participant_announcement_period and max_initial_participant_announcement_period. This randomness reduces the chances of a network collision when multiple participants are started at the same time.
DDS_Duration_t	max_initial_participant_announcement_period
DDS_Duration_t	participant_announcement_period	The period at which a participant announces itself to potential peers when using the 22.2 (Experimental) Simple Participant Discovery 2.0 (SPDP2). This field is not supported when using 22.1 Simple Participant Discovery; in that case, participant_liveliness_assert_period should be used instead.
Table 44.4 DDS_BuiltinTopicReaderResourceLimits_t	participant_reader_resource_limits	Configures the resource for the built-in DataReaders used to access discovery information; see 44.3.1 Resource Limits for Builtin-Topic DataReaders and 28. Accessing Discovery Information through Built-In Topics.
Table 48.2 DDS_RtpsReliableReaderProtocol_t	publication_reader	Configures the RTPS reliable protocol parameters for a built-in publication reader.
Table 44.4 DDS_BuiltinTopicReaderResourceLimits_t	publication_reader_resource_limits	Configures the resource for the built-in DataReaders used to access discovery information; see 44.3.1 Resource Limits for Builtin-Topic DataReaders and 28. Accessing Discovery Information through Built-In Topics.
Table 48.2 DDS_RtpsReliableReaderProtocol_t	subscription_reader	Configures the RTPS reliable protocol parameters for a built-in subscription reader. Built-in subscription readers receive discovery information reliably from DomainParticipants that were dynamically discovered (see 22. Discovery Overview).
Table 44.4 DDS_BuiltinTopicReaderResourceLimits_t	subscription_reader_resource_limits	Configures the resource for the built-in DataReaders used to access discovery information; see 44.3.1 Resource Limits for Builtin-Topic DataReaders and 28. Accessing Discovery Information through Built-In Topics.
Table 47.14 DDS_RtpsReliableWriterProtocol_t	publication_writer	Configures the RTPS reliable protocol parameters for the writer side of a reliable connection. Built-in DataWriters send reliable discovery information to DomainParticipants that were dynamically discovered (see 22. Discovery Overview).
Table 47.49 DDS_WriterDataLifecycleQosPolicy	publication_writer_data_lifecycle	Configures writer data-lifecycle settings for a built-in publication writer. (DDS_WriterDataLifecycleQosPolicy:: autodispose_unregistered_instances will always be TRUE.)
Table 47.14 DDS_RtpsReliableWriterProtocol_t	subscription_writer	Configures the RTPS reliable protocol parameters for the writer side of a reliable connection. Built-in DataWriters send reliable discovery information to DomainParticipants that were dynamically discovered (see 22. Discovery Overview).
Table 47.49 DDS_WriterDataLifecycleQosPolicy	subscription_writer_data_lifecycle	Configures writer data-lifecycle settings for a built-in subscription writer. (DDS_WriterDataLifecycleQosPolicy::autodispose_unregistered_instances will always be TRUE.)
DDS_DiscoveryConfigBuiltinPluginKindMask	builtin_discovery_plugins	The bit mask of available kinds for selecting builtin discovery plugins: (default) DDS_DISCOVERYCONFIG_BUILTIN_SDP: Enables the builtin Simple Discovery Protocol, which consists of both the 22.1 Simple Participant Discovery (SPDP) and the 22.3 Simple Endpoint Discovery (SEDP). DDS_DISCOVERYCONFIG_BUILTIN_SPDP: Enables only the 22.1 Simple Participant Discovery, which means that you intend to use a non-builtin alternative for endpoint discovery, such as Limited Bandwidth Endpoint Discovery (LBED). (Experimental) DDS_DISCOVERYCONFIG_BUILTIN_SPDP2: Enables an experimental version of the Simple Participant Discovery Protocol that is designed for decreased bandwidth usage and improved reliability. See22.2 (Experimental) Simple Participant Discovery 2.0 for more details. This participant discovery protocol must be enabled with an endpoint discovery plugin, such as the Simple Endpoint Discovery Protocol (SEDP). Note: It is not valid to enable both SPDP and SPDP2 at the same time. DDS_DISCOVERYCONFIG_BUILTIN_SEDP: Enables only the 22.3 Simple Endpoint Discovery, which means that you intend to use a non-builtin alternative for participant discovery, such as Limited Bandwidth Participant Discovery (LBPD). DDS_DISCOVERYCONFIG_BUILTIN_DPSE: Dynamic Participant discovery, Static Endpoint discovery (DPSE) enables SPDP for participant discovery and LBED for endpoint discovery. Using this value requires the Limited Bandwidth Endpoint Discovery (LBED) plug-in. See RTI Limited Bandwidth Endpoint Discovery Plugin User's Manual. DDS_DISCOVERYCONFIG_BUILTIN_PLUGIN_MASK_NONE: No builtin discovery is used. This setting should be used if you are replacing both endpoint and participant discovery algorithms with non-builtin alternatives. For example, MASK_NONE can be used when LBED and LBPD are both (simultaneously) enabled via the Limited Bandwidth Plugins.
DDS_DiscoveryConfigBuiltinChannelKindMask	enabled_builtin_channels	A bit mask specifying which builtin channels should be enabled. While there are a number of builtin channels that are used by Connext, the only built-in channel that can currently be enabled or disabled is the ServiceRequest channel. This channel is used by the locator reachability feature (see 26.2 Detection of Unreachable Locators) and TopicQuery feature (see 60. Topic Queries). If you are not using these features and wish to reduce network traffic and endpoint resource usage, you may disable the ServiceRequest channel with this field. The default value, DDS_DISCOVERYCONFIG_SERVICE_REQUEST_CHANNEL, enables the ServiceRequest channel, which is required by the TopicQuery and locator reachability features. Disabling the ServiceRequest channel reduces resource consumption including network bandwidth, CPU utilization, and memory. When the ServiceRequest channel is disabled, the TopicQuery and locator reachability features (which use the ServiceRequest channel) are disabled. Errors will be generated if you create a TopicQuery, enable TopicQuery dispatch, or enable locator reachability while the ServiceRequest channel is disabled.
DDS_ReliabilityQosPolicyKind	participant_message_reader_reliability_kind	Reliability kind configuration setting for a built-in participant message reader (default: best-effort). See Table 47.36 DDS_ReliabilityQosPolicy
Table 48.2 DDS_RtpsReliableReaderProtocol_t	participant_message_reader	RTPS protocol-related configuration settings for a built-in participant message reader.
Table 47.14 DDS_RtpsReliableWriterProtocol_t	participant_message_writer	RTPS protocol-related configuration settings for a built-in participant message writer.
Table 47.35 DDS_PublishModeQosPolicy	publication_writer_publish_mode	Determines whether the Discovery built-in publication DataWriter publishes data synchronously or asynchronously and how.
Table 47.35 DDS_PublishModeQosPolicy	subscription_writer_publish_mode	Determines whether the Discovery built-in subscription DataWriter publishes data synchronously or asynchronously and how.
Table 46.1 DDS_AsynchronousPublisherQosPolicy	asynchronous_publisher	Asynchronous publishing settings for the Discovery Publisher and all entities that are created by it.
DDS_Duration_t	default_domain_ announcement_period	The period at which a participant will announce itself to the default DDS domain 0 using the default UDPv4 multicast group address for discovery traffic on that DDS domain. For DDS domain 0, the default discovery multicast address is 239.255.0.1:7400. To disable announcement to the default DDS domain, set this to DURATION_INFINITE. When this period is set to a value other than DURATION_INFINITE and ignore_default_domain_announcements (see below) is FALSE, you can get information about participants running in different DDS domains by creating a participant in DDS domain 0 and implementing the on_data_available callback (see 40.7.1 DATA_AVAILABLE Status) in the ParticipantBuiltinTopicData built-in DataReader's listener (see 28.2 Built-in DataReaders). You can learn the domain ID associated with a participant by looking at the domain_id in the ParticipantBuiltinTopicData.
DDS_Boolean	ignore_default_domain_ announcements	When TRUE, ignores the announcements received by a participant on the default DDS domain 0 corresponding to participants running on domains IDs other than 0. This setting only applies to participants running on the default DDS domain 0 and using the default port mapping. When TRUE, a participant running on the default DDS domain 0 will ignore announcements from participants running on different DDS domain IDs. When FALSE, a participant running on the default DDS domain 0 will provide announcements from participants running on different DDS domain IDs to the application via the ParticipantBuiltinTopicData built-in DataReader (see 28.2 Built-in DataReaders).
Table 47.14 DDS_RtpsReliableWriterProtocol_t	service_request_writer	RTPS protocol-related configuration settings for the built-in service request writer.
Table 47.49 DDS_WriterDataLifecycleQosPolicy	service_request_writer_data_lifecycle	Configures writer data-lifecycle settings for the built-in service request writer.
Table 47.35 DDS_PublishModeQosPolicy)	service_request_writer_publish_mode	Determines whether the Discovery built-in service request DataWriter publishes data synchronously or asynchronously and how.
Table 48.1 DDS_DataReaderProtocolQosPolicy	service_request_reader	RTPS protocol-related configuration settings for the built-in service request reader.
DDS_Duration_t	locator_reachability_assert_period	Configures the period at which this DomainParticipant will ping all the locators that it has discovered from other DomainParticipants. This period should be strictly less than locator_reachability_lease_duration. If locator_reachability_lease_duration is INFINITE, this parameter is ignored. The DomainParticipant will not assert remote locators.
DDS_Duration_t	locator_reachability_lease_duration	For the purpose of this explanation, we use 'local' to refer to the DomainParticipant in which we configure locator_reachability_lease_duration and 'remote' to refer to the other DomainParticipants communicating with the local DomainParticipant. This setting configures a timeout announced to the remote DomainParticipants. This timeout is used by the remote DomainParticipants as the maximum period by which a remote locator must be asserted by the local DomainParticipant (through a REACHABILITY PING message) before considering this locator as "unreachable" from the local DomainParticipant. When a remote DomainParticipant detects that one of its locators is not reachable from the local DomainParticipant, it will notify the local DomainParticipant of this event. From that moment on, and until notified otherwise, the local DomainParticipant will not send RTPS messages to remote DomainParticipants using this locator. If this value is set to INFINITE, the local DomainParticipant will send RTPS messages to a remote DomainParticipant on the locators announced by the remote DomainParticipant, regardless of whether or not the remote DomainParticipant can be reached using these locators. By default, this field is set to INFINITE, meaning that the locator reachability feature is not enabled. To enable this feature, set this field to a value other than INFINITE.
DDS_Duration_t	locator_reachability_change_detection_period	Determines the maximum period at which this DomainParticipant will check to see if its locators are reachable from other DomainParticipants according to the other DomainParticipants' locator_reachability_lease_duration. If locator_reachability_lease_duration is INFINITE, this parameter is ignored. The DomainParticipant will not schedule an event to see if its locators are reachable from other DomainParticipants.
Table 47.14 DDS_RtpsReliableWriterProtocol_t	secure_volatile_writer	RTPS protocol-related configuration settings for the builtin Key Exchange writer.
Table 47.35 DDS_PublishModeQosPolicy	secure_volatile_writer_publish_mode	Publish mode policy for the builtin secure volatile writer. Determines whether the builtin secure volatile DataWriter publishes data synchronously or asynchronously and how.
Table 48.2 DDS_RtpsReliableReaderProtocol_t	secure_volatile_reader	RTPS protocol-related configuration settings for the builtin Key Exchange reader.
DDS_Long	endpoint_type_object_lb_serialization_threshold	Minimum size (in bytes) of the serialized TypeObject that will trigger the serialization of a TypeObjectLb instead of the regular TypeObject. TypeObjectLb is a compressed version of the serialized TypeObject. This compressed version reduces the size needed to propagate a TypeObject as part of Simple Endpoint Discovery. For example, setting this policy to 1000 will trigger the serialization of the TypeObjectLb for TypeObjects whose serialized size is greater than 1000 Bytes. Range: [-1, 2147483647]. The sentinel value -1 disables TypeObject compression (by never sending TypeObjectLb). Any non-valid values will behave as 0. Default: 0 (TypeObjectLb is enabled by default)
DDS_Duration_t	dns_tracker_polling_period	Configures the frequency used by the DNS Tracker thread to query the DNS service. If this parameter is set to INFINITE, the DNS tracker is disabled and changes in hostnames will not be tracked. See 26.3 Using DNS Tracker to Keep Peer List Updated for more information.

When a DomainParticipant is first enabled, it sends out initial_participant_announcements number of participant messages to the peers on its initial_peers list. These messages are sent at a random time between min/max_initial_participant_announcement_period.

After a DomainParticipant has sent out initial_participant_announcements, it needs to send a message periodically to let other participants know that it is still alive as well as to discover new participants that may join the system. These messages are sent to all peers in the peer list that was initialized by the initial_peers parameter of the 44.2 DISCOVERY QosPolicy (DDS Extension) and to any peers that have been discovered that were not on the initial_peers list (if accept_unknown_peers is true). The peer DomainParticipants that already know about this DomainParticipant will use the participant_liveliness_lease_duration provided by this participant to declare the participant dead if they have not received a participant message for the specified time.

The participant_liveliness_assert_period is the periodic rate at which this DomainParticipant will be sending periodic participant messages. Since these messages are not sent reliably and can get dropped by the transport, it is important to set:

participant_liveliness_assert_period < participant_liveliness_lease_duration / N

where N is the number of liveliness messages that other DomainParticipants must miss before they decide that this DomainParticipant is dead.

DomainParticipants that receive a participant message from a participant that they did not know about previously will have “discovered” the participant. When one DomainParticipant discovers another, the discoverer will immediately send its own participant messages back. new_remote_participant_announcements controls how many of these messages are sent only to newy discovered participants, and min/max_initial_participant_announcement_period controls the time period in between each message.

For more information on the discovery process, see 22. Discovery Overview.

44.3.1 Resource Limits for Builtin-Topic DataReaders

The DDS_BuiltinTopicReaderResourceLimits_t structure is shown in Table 44.4 DDS_BuiltinTopicReaderResourceLimits_t. This structure contains several fields that are used to configure the resource limits of the builtin-topic DataReaders used to receive discovery meta-traffic from other DomainParticipants.

Table 44.4 DDS_BuiltinTopicReaderResourceLimits_t
Type	Field Name	Description
DDS_Long	initial_samples	Initial number of meta-traffic DDS data samples that can be stored by a builtin-topic DataReader.
	max_samples	Maximum number of meta-traffic DDS data samples that can be stored by a builtin-topic DataReader.
	initial_infos	Initial number of DDS_SampleInfo structures allocated for the builtin-topic DataReader.
	max_infos	Maximum number of DDS_SampleInfo structures that can be allocated for the built-in topic DataReader. max_infos must be >= max_samples
	initial_outstanding_reads	Initial number of times in which memory can be concurrently loaned via read/take calls on the builtin-topic DataReader without being returned with return_loan().
	max_outstanding_reads	Maximum number of times in which memory can be concurrently loaned via read/take calls on the builtin-topic DataReader without being returned with return_loan().
	max_samples_per_read	Maximum number of DDS samples that can be read/taken on a same built-in topic DataReader.
DDS_Boolean	disable_fragmentation_support	Determines whether the builtin-topic DataReader can receive fragmented DDS samples. When fragmentation support is not needed, disabling fragmentation support will save some memory resources.
DDS_Long	max_fragmented_samples	The maximum number of DDS samples for which the DataReader may store fragments at a given point in time. At any given time, a DataReader may store fragments for up to max_fragmented_samples DDS samples while waiting for the remaining fragments. These DDS samples need not have consecutive sequence numbers and may have been sent by different DataWriters. Once all fragments of a DDS sample have been received, the DDS sample is treated as a regular DDS sample and becomes subject to standard QoS settings, such as max_samples. Connext will drop fragments if the max_fragmented_samples limit has been reached. For best-effort communication, Connext will accept a fragment for a new DDS sample, but drop the oldest fragmented DDS sample from the same remote writer. For reliable communication, Connext will drop fragments for any new DDS samples until all fragments for at least one older DDS sample from that writer have been received. Only applies if disable_fragmentation_support is FALSE.
DDS_Long	initial_fragmented_samples	The initial number of DDS samples for which a builtin-topic DataReader may store fragments. Only applies if disable_fragmentation_support is FALSE.
DDS_Long	max_fragmented_samples_per_remote_writer	The maximum number of DDS samples per remote writer for which a builtin-topic DataReader may store fragments. Logical limit so a single remote writer cannot consume all available resources. Only applies if disable_fragmentation_support is FALSE.
DDS_Long	max_fragments_per_sample	Maximum number of fragments for a single DDS sample. Only applies if disable_fragmentation_support is FALSE.
DDS_Boolean	dynamically_allocate_ fragmented_samples	By default, the middleware does not allocate memory upfront, but instead allocates memory from the heap upon receiving the first fragment of a new sample. The amount of memory allocated equals the amount of memory needed to store all fragments in the sample. Once all fragments of a sample have been received, the sample is deserialized and stored in the regular receive queue. At that time, the dynamically allocated memory is freed again. This QoS setting is useful for large, but variable-sized data types where up-front memory allocation for multiple samples based on the maximum possible sample size may be expensive. The main disadvantage of not pre-allocating memory is that one can no longer guarantee the middleware will have sufficient resources at run-time. If dynamically_allocate_fragmented_samples is FALSE, the middleware will allocate memory up-front for storing fragments for up to initial_fragmented_samples samples. This memory may grow up to max_fragmented_samples if needed. Only applies if disable_fragmentation_support is FALSE.

There are builtin-topics for exchanging data about DomainParticipants, for publications (Publisher/DataWriter combination) and for subscriptions (Subscriber/DataReader combination). The DataReaders for the publication and subscription builtin-topics are reliable. The DataReader for the participant builtin-topic is best effort.

You can set listeners on these DataReaders that are created automatically when a DomainParticipant is created. With these listeners, your code can be notified when remote DomainParticipants, Publishers/DataWriters, and Subscriber/DataReaders are discovered. You can always check the receive queues of those DataReaders for the same information about discovered entities at any time. Please see 28. Accessing Discovery Information through Built-In Topics for more details.

The initial_samples and max_samples, and related initial_infos and max_infos, fields size the amount of declaration messages can be stored in each builtin-topic DataReader.

44.3.2 Controlling Purging of Remote Participants

When discovery communication with a remote participant has been lost, the local participant must make a decision about whether to continue attempting to communicate with that participant and its contained entities. The remote_participant_purge_kind is used to select the desired behavior.

This does not pertain to the situation in which a remote participant has been gracefully deleted and notification of that deletion has been successfully received by its peers. In that case, the local participant will immediately stop attempting to communicate with those entities and will remove the associated remote entity records from its internal database.

The remote_participant_purge_kind can be set to the following values:

In most cases, you will not need to change this value from its default, DDS_LIVELINESS_BASED_REMOTE_PARTICIPANT_PURGE.

However, DDS_NO_REMOTE_PARTICIPANT_PURGE may be a good choice if the following conditions apply:

Discovery communication with a remote participant may be lost while data communication remains intact. This will not be the typical case if discovery takes place over the Simple Discovery Protocol.

Extensive and prolonged lack of discovery communication between participants is not expected to be common, either because loss of the participant will be rare, or because participants may be lost sporadically but will typically return again.

Maintaining inter-participant liveliness is problematic, perhaps because a participant has no writers with the appropriate 47.15 LIVELINESS QosPolicy kind.

44.3.3 Controlling the Reliable Protocol Used by Builtin-Topic DataWriters/DataReaders

The connection between the DataWriters and DataReaders for the publication and subscription builtin-topics are reliable. The publication_writer, subscription_writer, publication_reader, and subscription_reader parameters of the 44.3 DISCOVERY_CONFIG QosPolicy (DDS Extension) configure the reliable messaging protocol used by Connext for those topics. Connext’s reliable messaging protocol is discussed in 32. Reliability Models for Sending Data.

44.3.4 Example

Users will be most interested in setting the participant_liveliness_lease_duration and participant_liveliness_assert_period values for their DomainParticipants. Basically, the lease duration governs how fast an application realizes another application dies unexpectedly. The shorter the periods, the quicker a DomainParticipant can determine that a remote participant is dead and act accordingly by declaring all of the remote DataWriters and DataReaders of that participant dead as well.

However, you should realize that the shorter the period the more liveliness packets will sent by the DomainParticipant. How many packets is also determined by the number of peers in the peer list of the participant–whether or not the peers on the list are actually alive.

44.3.5 Properties

This QosPolicy cannot be modified after the DomainParticipant is created.

It can be set differently on the publishing and subscribing sides.

44.3.6 Related QosPolicies

44.3.7 Applicable DDS Entities

16.3 DomainParticipants

44.3.8 System Resource Considerations

Setting smaller values for time periods can increase the CPU and network bandwidth usage. Setting larger values for maximum limits can increase the maximum memory that Connext may allocate for a DomainParticipant while increasing the initial values will increase the initial memory allocated for a DomainParticipant.