Open topic with navigation

Getting, Setting, and Comparing QosPolicies

Each type of Entity has an associated set of QosPolicies (see QosPolicies). QosPolicies allow you to configure and set properties for the Entity.

While most QosPolicies are defined by the DDS specification, some are offered by Connext DDS as extensions to control parameters specific to the implementation.

There are two ways to specify a QoS policy:

The get_qos() operation retrieves the current values for the set of QosPolicies defined for the Entity.

QosPolicies can be set programmatically when an Entity is created, or modified with the Entity's set_qos() operation.

The set_qos() operation sets the QosPolicies of the entity. Note: not all QosPolicy changes will take effect instantaneously; there may be a delay since some QosPolicies set for one entity, for example, a DataReader, may actually affect the operation of a matched entity in another application, for example, a DataWriter.

The get_qos() and set_qos() operations are passed QoS structures that are specific to each derived entity class, since the set of QosPolicies that effect each class of Entities is different.

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

Each QosPolicy has default values (listed in the API Reference HTML documentation). If you want to use custom values, there are three ways to change QosPolicy settings:

Regardless of when or how you make QoS changes, there are some rules to follow:

Changing the QoS Defaults Used to Create DDS Entities: set_default_*_qos()

Each parent factory has a set of default QoS settings that are used when the child entity is created. The DomainParticipantFactory has default QoS values for creating DomainParticipants. A DomainParticipant has a set of default QoS for each type of entity that can be created from the DomainParticipant (Topic, Publisher, Subscriber, DataWriter, and DataReader). Likewise, a Publisher has a set of default QoS values used when creating DataWriters, and a Subscriber has a set of default QoS values used when creating DataReaders.

An entity’s QoS are set when it is created. Once an entity is created, all of its QoS—for itself and its child Entities—are fixed unless you call set_qos() or set_qos_with_profile() on that entity. Calling set_default_<entity>_qos() on a parent entity will have no effect on child Entities that have already been created.

You can change these default values so that they are automatically applied when new child Entities are created. For example, suppose you want all DataWriters for a particular Publisher to have their RELIABILITY QosPolicy set to RELIABLE. Instead of making this change for each DataWriter when it is created, you can change the default used when any DataWriter is created from the Publisher by using the Publisher’s set_default_datawriter_qos() operation.

DDS_DataWriterQos default_datawriter_qos;
// get the current default values
publisher->get_default_datawriter_qos(default_datawriter_qos);
// change to desired default values
default_datawriter_qos.reliability.kind =
		DDS_RELIABLE_RELIABILITY_QOS;
// set the new default values
publisher->set_default_datawriter_qos(default_datawriter_qos);
// created datawriters will use new default values
datawriter = 
    publisher->create_datawriter(topic, NULL, NULL, NULL);

It is not safe to get or set the default QoS values for an entity while another thread may be simultaneously calling get_default_<entity>_qos(), set_default_<entity>_qos(), or create_<entity>() with DDS_<ENTITY>_QOS_DEFAULT as the qos parameter (for the same entity).

Another way to make QoS changes is by using XML resources (files, strings). For more information, see Configuring QoS with XML.

Setting QoS During Entity Creation

If you only want to change a QosPolicy for a particular entity, you can pass in the desired QosPolicies for an entity in its creation routine.

To customize an entity's QoS before creating it:

  1. (C API Only) Initialize a QoS object with the appropriate INITIALIZER constructor.
  2. Call the relevant get_<entity>_default_qos() method.
  3. Modify the QoS values as desired.
  4. Create the entity.
ClosedFor example, to change the RELIABLE QosPolicy for a DataWriter before creating it: 
// Initialize the QoS object
DDS_DataWriterQos datawriter_qos;
// Get the default values
publisher->get_default_datawriter_qos(datawriter_qos);
// Modify the QoS values as desired
datawriter_qos.reliability.kind = DDS_BEST_EFFORT_RELIABILITY_QOS;
// Create the DataWriter with new values
datawriter = publisher->create_datawriter(
    topic, datawriter_qos, NULL, NULL);

Another way to set QoS during entity creation is by using a QoS profile. For more information, see Configuring QoS with XML.

Changing the QoS for an Existing Entity

Some policies can also be changed after the entity has been created. To change such a policy after the entity has been created, use the entity’s set_qos() operation.

For example, suppose you want to tweak the DEADLINE QoS for an existing DataWriter:

DDS_DataWriterQos datawriter_qos;
// get the current values
datawriter->get_qos(datawriter_qos);
// make desired changes
datawriter_qos.deadline.period.sec = 3;
datawriter_qos.deadline.period.nanosec = 0;
// set new values
datawriter->set_qos(datawriter_qos);

Another way to make QoS changes is by using a QoS profile. For more information, see Configuring QoS with XML.

Note: In the code examples presented in this section, we are not testing for the return code for the set_qos(), set_default_*_qos() functions. If the values used in the QosPolicy structures are inconsistent then the functions will fail and return INCONSISTENT_POLICY. In addition, set_qos() may return IMMUTABLE_POLICY if you try to change a QosPolicy on an Entity after that policy has become immutable. User code should test for and address those anomalous conditions.

Default QoS Values

Connext DDS provides special constants for each Entity type that can be used in set_qos() and set_default_*_qos() to reset the QosPolicy values to the original DDS default values:

For example, if you want to set a DataWriter’s QoS back to their DDS-specified default values:

datawriter->set_qos(DDS_DATAWRITER_QOS_DEFAULT);

Or if you want to reset the default QosPolicies used by a Publisher to create DataWriters back to their DDS-specified default values:

publisher->set_default_datawriter_qos(DDS_DATAWRITER_QOS_DEFAULT);

These defaults cannot be used to initialize a QoS structure for an entity. For example, the following is NOT allowed:

DataWriterQos dataWriterQos = DATAWRITER_QOS_DEFAULT;
// modify QoS...
create_datawriter(dataWriterQos);

© 2018 RTI

Open topic with navigation