DISCOVERY_CONFIG QosPolicy (DDS Extension)

You are here: Part 2: Core Concepts > Working with DDS Domains > DomainParticipant QosPolicies > DISCOVERY_CONFIG QosPolicy (DDS Extension)

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 (e.g. 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 . Many of these members are described in Discovery. For defaults and valid ranges, please refer to the API Reference HTML documentation.

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.
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 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 liveliness announcements the DomainParticipant will send when it is first enabled, or after discovering a new remote participant.
DDS_Duration_t	min_initial_participant_ announcement_period	Sets the minimum and maximum times between liveliness announcements. When a participant is first enabled, or after discovering a new remote participant, Connext DDS sends initial_paricipant_annoucements number of discovery messages. These messages are sent with a sleep period between them that is a random duration between min_initial_participant_announcement_period and max_initial_participant_announcement_period.
DDS_Duration_t	max_initial_participant_ announcement_period
DDS_BuiltinTopicReaderResourceLimits_t	participant_reader_ resource_limits	Configures the resource for the built-in DataReaders used to access discovery information; see Resource Limits for Builtin-Topic DataReaders and Built-In Topics.
DDS_RtpsReliableReaderProtocol_t	publication_reader	Configures the RTPS reliable protocol parameters for a built-in publication reader.
DDS_BuiltinTopicReaderResourceLimits_t	publication_reader_ resource_limits	Configures the resource for the built-in DataReaders used to access discovery information; see Resource Limits for Builtin-Topic DataReaders and Built-In Topics.
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 Discovery).
DDS_BuiltinTopicReaderResourceLimits_t	subscription_reader_ resource_limits	Configures the resource for the built-in DataReaders used to access discovery information; see Resource Limits for Builtin-Topic DataReaders and Built-In Topics.
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 Discovery).
WRITER_DATA_LIFECYCLE QoS Policy	publication_writer_data_lifecycle	Configures writer data-lifecycle settings for a built-in publication writer. (DDS_WriterDataLifecycleQosPolicy:: autodispose_unregistered_instances will always be TRUE.)
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 Discovery).
WRITER_DATA_LIFECYCLE QoS Policy	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 kind mask for selecting built-in discovery plugins. Simple Discovery Protocol: DDS_DISCOVERYCONFIG_BUILTIN_SDP
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 DATA_AVAILABLE Status) in the ParticipantBuiltinTopicData built-in DataReader's listener (see 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 Built-in DataReaders).
DDS_RtpsReliableReaderProtocol_t	participant_message_ reader	RTPS protocol-related configuration settings for a built-in participant message reader.
DDS_ReliabilityQosPolicyKind See DDS_ReliabilityQosPolicy	participant_message_reader_reliability_kind	Reliability kind configuration setting for a built-in participant message reader (default: best-effort).
DDS_RtpsReliableWriterProtocol_t	participant_message_ writer	RTPS protocol-related configuration settings for a built-in participant message writer.
PUBLISH_MODE QosPolicy (DDS Extension)	publication_writer_ publish_mode	Determines whether the Discovery built-in publication DataWriter publishes data synchronously or asynchronously and how.
PUBLISH_MODE QosPolicy (DDS Extension)	subscription_writer_ publish_mode	Determines whether the Discovery built-in subscription DataWriter publishes data synchronously or asynchronously and how.
ASYNCHRONOUS_PUBLISHER QosPolicy (DDS Extension)	asynchronous_publisher	Asynchronous publishing settings for the Discovery Publisher and all entities that are created by it.

A DomainParticipant needs to send a message periodically to other DomainParticipants to let the other participants know that it is still alive. These liveliness messages are sent to all peers in the peer list that was initialized by the initial_peers parameter of the DISCOVERY QosPolicy (DDS Extension). Peer participants on the peer list may or may not be alive themselves. 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 liveliness message for the specified time.

The participant_liveliness_assert_period is the periodic rate at which this DomainParticipant will be sending liveliness messages. Since these liveliness 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 liveliness 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 liveliness packets back. initial_participant_announcements controls how many of these initial liveliness messages are sent, and max_initial_participant_announcement_period controls the time period in between each message.

After the initial set of liveliness messages are sent, the DomainParticipant will return to sending liveliness packets to all peers in its peer list at the rate governed by participant_liveliness_assert_period.

For more information on the discovery process, see Discovery.

Resource Limits for Builtin-Topic DataReaders

The DDS_BuiltinTopicReaderResourceLimits_t structure is shown in . 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.

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 DDS will drop fragments if the max_fragmented_samples limit has been reached. For best-effort communication, Connext DDS 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 DDS 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 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.

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:

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 LIVELINESS QosPolicy kind.

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 DISCOVERY_CONFIG QosPolicy (DDS Extension) configure the reliable messaging protocol used by Connext DDS for those topics. Connext DDS’s reliable messaging protocol is discussed in Reliable Communications.

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.

Properties

This QosPolicy cannot be modified after the DomainParticipant is created.

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

Related QosPolicies

Applicable Dds Entities

DomainParticipants

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 DDS may allocate for a DomainParticipant while increasing the initial values will increase the initial memory allocated for a DomainParticipant.