Setting DomainParticipant QosPolicies

A DomainParticipant’s QosPolicies are used to configure discovery, database sizing, threads, information sent to other DomainParticipants, and the behavior of the DomainParticipant when acting as a factory for other Entities.

Note: set_qos() cannot always be used in a listener callback; see Restricted Operations in Listener Callbacks.

The DDS_DomainParticipantQos structure has the following format:

struct DDS_DomainParticipantQos {
	DDS_UserDataQosPolicy  			user_data; 
	DDS_EntityFactoryQosPolicy 		entity_factory; 
	DDS_WireProtocolQosPolicy 		wire_protocol; 
	DDS_TransportBuiltinQosPolicy		transport_builtin;
	DDS_TransportUnicastQosPolicy		default_unicast;
	DDS_DiscoveryQosPolicy 			discovery; 
	DDS_DomainParticipantResourceLimitsQosPolicy  resource_limits;
	DDS_EventQosPolicy  			event; 
	DDS_ReceiverPoolQosPolicy  		receiver_pool; 
	DDS_DatabaseQosPolicy  			database; 
	DDS_DiscoveryConfigQosPolicy 		discovery_config;
	DDS_PropertyQosPolicy			property;
	DDS_EntityNameQosPolicy			participant_name;
	DDS_TransportMulticastMappingQosPolicy	multicast_mapping;
	DDS_ServiceQosPolicy			service;
	DDS_TypeSupportQosPolicy		type_support;
};

DomainParticipant QosPolicies summarizes the meaning of each policy (listed alphabetically). For information on why you would want to change a particular QosPolicy, see the section referenced in the table.

DomainParticipant QosPolicies

QosPolicy	Description
Database	Various settings and resource limits used by Connext DDS to control its internal database. See DATABASE QosPolicy (DDS Extension).
Discovery	Configures the mechanism used by Connext DDS to automatically discover and connect with new remote applications. See DISCOVERY QosPolicy (DDS Extension).
DiscoveryConfig	Controls the amount of delay in discovering entities in the system and the amount of discovery traffic in the network. See DISCOVERY_CONFIG QosPolicy (DDS Extension).
DomainParticipantResourceLimits	Various settings that configure how DomainParticipants allocate and use physical memory for internal resources, including the maximum sizes of various properties. See DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension).
EntityFactory	Controls whether or not child entities are created in the enabled state. See ENTITYFACTORY QosPolicy.
EntityName	Assigns a name to a DomainParticipant. See ENTITY_NAME QosPolicy (DDS Extension).
Event	Configures the DomainParticipant’s internal thread that handles timed events. See EVENT QosPolicy (DDS Extension).
Property	Stores name/value(string) pairs that can be used to configure certain parameters of Connext DDS that are not exposed through formal QoS policies. It can also be used to store and propagate application-specific name/value pairs, which can be retrieved by user code during discovery. See PROPERTY QosPolicy (DDS Extension) .
ReceiverPool	Configures threads used by Connext DDS to receive and process data from transports (for example, UDP sockets). See RECEIVER_POOL QosPolicy (DDS Extension).
Service	Intended for use by RTI infrastructure services. User applications should not modify its value. See SERVICE QosPolicy (DDS Extension).
TransportBuiltin	Specifies which built-in transport plugins are used. See TRANSPORT_BUILTIN QosPolicy (DDS Extension).
TransportMulticastMapping	Specifies the automatic mapping between a list of topic expressions and multicast address that can be used by a DataReader to receive data for a specific topic. See TRANSPORT_MULTICAST_MAPPING QosPolicy (DDS Extension).
TransportUnicast	Specifies a subset of transports and port number that can be used by an Entity to receive data. See TRANSPORT_UNICAST QosPolicy (DDS Extension).
TypeSupport	Used to attach application-specific value(s) to a DataWriter or DataReader. These values are passed to the serialization or deserialization routine of the associated data type. See TYPESUPPORT QosPolicy (DDS Extension).
UserData	Along with Topic Data QosPolicy and Group Data QosPolicy, used to attach a buffer of bytes to Connext DDS's discovery meta-data. See USER_DATA QosPolicy.
WireProtocol	Specifies IDs used by the RTPS wire protocol to create globally unique identifiers. See WIRE_PROTOCOL QosPolicy (DDS Extension).

Configuring QoS Settings when DomainParticipant is Created

As described in Creating a DomainParticipant, there are different ways to create a DomainParticipant, depending on how you want to specify its QoS (with or without a QoS Profile).

• Figure: Creating a DomainParticipant with Default QosPolicies has an example of how to create a DomainParticipant with default QosPolicies by using the special constant, DDS_PARTICIPANT_QOS_DEFAULT, which indicates that the default QoS values for a DomainParticipant should be used. The default DomainParticipant QoS values are configured in the DomainParticipantFactory; you can change them with set_default_participant_qos() or set_default_participant_qos_with_profile() (see Getting and Setting Default QoS for DomainParticipants). Then any DomainParticipants created with the DomainParticipantFactory will use the new default values. As described in Getting, Setting, and Comparing QosPolicies, this is a general pattern that applies to the construction of all Entities.
• To create a DomainParticipant with non-default QoS without using a QoS Profile, see the example code in Figure: Creating DomainParticipant with Modified QosPolicies (not from profile). It uses the DomainParticipantFactory’s get_default_participant_qos() method to initialize a DDS_ParticipantQos structure. Then, the policies are modified from their default values before the structure is used in the create_participant() method.
• You can also create a DomainParticipant and specify its QoS settings via a QoS Profile. To do so, you will call create_participant_with_profile(), as seen in Figure: Creating DomainParticipant with QoS Profile.
• If you want to use a QoS profile, but then make some changes to the QoS before creating the DomainParticipant, call get_participant_qos_from_profile() and create_participant() as seen in Figure: Getting QoS from Profile, Creating DomainParticipant with Modified QoS Values.

For more information, see Creating a DomainParticipant and Configuring QoS with XML.

Figure: Creating DomainParticipant with Modified QosPolicies (not from profile)

DDS_DomainId_t domain_id = 10;
DDS_DomainParticipantQos participant_qos;1In C, you must initialize the QoS structures before they are used, see Special QosPolicy Handling Considerations for C.
// initialize participant_qos with default values
factory->get_default_participant_qos(participant_qos);
// make QoS changes here
participant_qos.wire_protocol.participant_id = 2;
// Create the participant with modified qos
DDSDomainParticipant* participant = factory->create_participant(
	domain_id, participant_qos, NULL, DDS_STATUS_MASK_NONE);
if (participant == NULL) {
	// ... error
}

Figure: Creating DomainParticipant with QoS Profile

DDS_DomainId_t domain_id = 10;
// MyDomainParticipantListener is user defined and
// extends DDSDomainParticipantListener
MyDomainParticipantListener* participant_listener
	= new MyDomainParticipantListener(); // or = NULL
// Create the participant
DDSDomainParticipant* participant =
	factory->create_participant_with_profile(domain_id,
	“MyDomainLibrary”, “MyDomainProfile”,		
	participant_listener, DDS_STATUS_MASK_ALL);
if (participant == NULL) {
	// ... error
};

Figure: Getting QoS from Profile, Creating DomainParticipant with Modified QoS Values

DDS_DomainParticipantQos participant_qos;2In C, you must initialize the QoS structures before they are used, see Special QosPolicy Handling Considerations for C.
// Get DomainParticipant QoS from profile
retcode = factory->get_participant_qos_from_profile( participant_qos,
	“DomainParticipantProfileLibrary”, “DomainParticipantProfile”);
if (retcode != DDS_RETCODE_OK) {
	// handle error
}
// Makes QoS changes here
participant_qos.entity_factory.autoenable_created_entities = DDS_BOOLEAN_FALSE;
// create participant with modified QoS
DDSDomainParticipant* participant = factory->create_participant(domain_id,
	participant_qos, NULL, DDS_STATUS_MASK_NONE);
if (participant == NULL) {
	// handle error
}

Comparing QoS Values

The equals() operation compares two DomainParticipant’s DDS_DomainParticipantQoS structures for equality. It takes two parameters for the two DomainParticipant’s QoS structures to be compared, then returns TRUE is they are equal (all values are the same) or FALSE if they are not equal.

Changing QoS Settings After DomainParticipant Has Been Created

There are two ways to change an existing DomainParticipant’s QoS after it is has been created—again depending on whether or not you are using a QoS Profile.

• To change QoS programmatically (that is, without using a QoS Profile), use get_qos() and set_qos(). See the example code in Figure: Changing QoS of Existing Participant (without QoS Profile). It retrieves the current values by calling the DomainParticipant’s get_qos() operation. Then it modifies the value and calls set_qos() to apply the new value. Note, however, that some QosPolicies cannot be changed after the DomainParticipant has been enabled—this restriction is noted in the descriptions of the individual QosPolicies.
• You can also change a DomainParticipant’s (and all other Entities’) QoS by using a QoS Profile and calling set_qos_with_profile(). For an example, see Figure: Changing QoS of Existing Participant with QoS Profile . For more information, see Configuring QoS with XML.

Figure: Changing QoS of Existing Participant (without QoS Profile)

DDS_DomainParticipantQos participant_qos;3In C, you must initialize the QoS structures before they are used, see Special QosPolicy Handling Considerations for C.
// Get current QoS
//participant points to an existing DDSDomainParticipant
if (participant->get_qos(participant_qos) != DDS_RETCODE_OK) {
	// handle error
}
// Make QoS changes
participant_qos.entity_factory.autoenable_created_entities =
	DDS_BOOLEAN_FALSE;
// Set the new QoS
if (participant->set_qos(participant_qos) != DDS_RETCODE_OK ) {
	// handle error
}

Figure: Changing QoS of Existing Participant with QoS Profile

DDS_DomainParticipantQos participant_qos;4In C, you must initialize the QoS structures before they are used, see Special QosPolicy Handling Considerations for C.
// Get current QoS
//participant points to an existing DDSDomainParticipant
if (participant->get_qos(participant_qos) != DDS_RETCODE_OK) {
	// handle error
}
// Make QoS changes
participant_qos.entity_factory.autoenable_created_entities =
	DDS_BOOLEAN_FALSE;
// Set the new QoS
if (participant->set_qos(participant_qos) != DDS_RETCODE_OK ) {
	// handle error
}

Getting and Setting DomainParticipant’s Default QoS Profile and Library

You can get the default QoS profile for the DomainParticipant with the get_default_profile() operation. You can also get the default library for the DomainParticipant, as well as the library that contains the DomainParticipant’s default profile (these are not necessarily the same library); these operations are called get_default_library() and get_default_library_profile(), respectively. These operations are for informational purposes only (that is, you do not need to use them as a precursor to setting a library or profile.) For more information, see Configuring QoS with XML.

virtual const char *  get_default_library ()
const char *  get_default_profile ()
const char *  get_default_profile_library ()

There are also operations for setting the DomainParticipant’s default library and profile:

DDS_ReturnCode_t set_default_library  (
    const char *  library_name) 
DDS_ReturnCode_t set_default_profile (
    const char *  library_name,
    const char *  profile_name) 

If the default profile/library is not set, the DomainParticipant inherits the default from the DomainParticipantFactory.

• set_default_profile() specifies the profile that will be used as the default the next time a default DomainParticipant profile is needed during a call to one of this DomainParticipant’s operations. When calling a DomainParticipant operation that requires a profile_name parameter, you can use NULL to refer to the default profile. (This same information applies to setting a default library.)
• set_default_profile() does not set the default QoS for entities created by the DomainParticipant; for this functionality, use the DomainParticipant’s set_default_<entity>_qos_with_profile() operation (you may pass in NULL after having called set_default_profile(), see Getting and Setting Default QoS for Child Entities).
• set_default_profile() does not set the default QoS for newly created DomainParticipants; for this functionality, use the DomainParticipantFactory’s set_default_participant_qos_with_profile(), see Getting and Setting Default QoS for DomainParticipants).

Getting and Setting Default QoS for Child Entities

The set_default_<entity>_qos() and set_default_<entity>_qos_with_profile() operations set the default QoS that will be used for newly created entities (where <entity> may be publisher, subscriber, datawriter, datareader, or topic). The new QoS settings will only be used if DDS_<entity>_QOS_DEFAULT is specified as the qos parameter when create_<entity>() is called. For example, for a Publisher, you can use either:

DDS_ReturnCode_t set_default_publisher_qos (
    const DDS_PublisherQos &qos)
DDS_ReturnCode_t set_default_publisher_qos_with_profile (
    const char *library_name, 
    const char *profile_name)

The following operation gets the default QoS that will be used for creating Publishers if DDS_PUBLISHER_QOS_DEFAULT is specified as the ‘qos’ parameter when create_publisher() is called:

DDS_ReturnCode_t get_default_publisher_qos (
    DDS_PublisherQos & qos)

There are similar operations for Subscribers, DataWriters, DataReaders and Topics. These operations, get_default_<entity>_qos(), get the QoS settings that were specified on the last successful call to set_default_<entity>_qos() or set_default_<entity>_qos_with_profile(), or if the call was never made, the default values listed in DDS_<entity>Qos. They may potentially allocate memory depending on the sequences contained in some QoS policies.

Note: It is not safe to set default QoS values for an entity while another thread may be simultaneously getting or setting them, or using the QOS_DEFAULT constant to create the entity.

© 2018 RTI