40.9 Setting DataReader QosPolicies
A DataReader’s QosPolicies control its behavior. Think of QosPolicies as the 'properties' of a DataReader.
The DDS_DataReaderQos structure has the following format:
DDS_DataWriterQos struct {
DDS_DurabilityQosPolicy durability;
DDS_DeadlineQosPolicy deadline;
DDS_LatencyBudgetQosPolicy latency_budget;
DDS_LivelinessQosPolicy liveliness;
DDS_ReliabilityQosPolicy reliability;
DDS_DestinationOrderQosPolicy destination_order;
DDS_HistoryQosPolicy history;
DDS_ResourceLimitsQosPolicy resource_limits;
DDS_UserDataQosPolicy user_data;
DDS_OwnershipQosPolicy ownership;
DDS_TimeBasedFilterQosPolicy time_based_filter;
DDS_ReaderDataLifecycleQosPolicy reader_data_lifecycle;
DDS_DataRepresentationQosPolicy representation;
DDS_TypeConsistencyEnforcementQosPolicy type_consistency;
DDS_DataTagQosPolicy data_tags;
// extensions to the DDS standard:
DDS_DataReaderResourceLimitsQosPolicy reader_resource_limits;
DDS_DataReaderProtocolQosPolicy protocol;
DDS_TransportSelectionQosPolicy transport_selection;
DDS_TransportUnicastQosPolicy unicast;
DDS_TransportMulticastQosPolicy multicast;
DDS_PropertyQosPolicy property;
DDS_ServiceQosPolicy service;
DDS_AvailabilityQosPolicy availability;
DDS_EntityNameQosPolicy subscription_name;
DDS_TransportPriorotyQosPolicy transport_priority;
DDS_TypeSupportQosPolicy type_support;
} DDS_DataReaderQos;
Note: set_qos() cannot always be used within a listener callback, see 15.8.8.1 Restricted Operations in Listener Callbacks.
Table 40.13 DataReader QosPolicies summarizes the meaning of each policy. (They appear alphabetically in the table.) For information on why you would want to change a particular QosPolicy, see the referenced section. For defaults and valid ranges, please refer to the API Reference HTML documentation.
QosPolicy |
Description |
Availability |
This QoS policy is used in the context of two features:
|
DataReaderProtocol |
This QosPolicy configures the DDS on-the-network protocol, RTPS. See 48.1 DATA_READER_PROTOCOL QosPolicy (DDS Extension). |
DataReaderResourceLimits |
Various settings that configure how DataReaders allocate and use physical memory for internal resources. See 48.2 DATA_READER_RESOURCE_LIMITS QosPolicy (DDS Extension). |
DataRepresentation |
Specifies which versions of the Extended Common Data Representation (CDR) are requested. See 47.3 DATA_REPRESENTATION QosPolicy. |
DataTag |
A sequence of (name, value) string pairs that may be used by the Access Control plugin. See 47.4 DATATAG QosPolicy. |
Deadline |
For a DataReader, it specifies the maximum expected elapsed time between arriving DDS data samples. For a DataWriter, it specifies a commitment to publish DDS samples with no greater elapsed time between them. |
DestinationOrder |
Controls how Connext will deal with data sent by multiple DataWriters for the same topic. Can be set to "by reception timestamp" or to "by source timestamp". See 47.8 DESTINATION_ORDER QosPolicy. |
Durability |
Specifies whether or not Connext will store and deliver data that were previously published to new DataReaders. See 47.9 DURABILITY QosPolicy. |
EntityName |
Assigns a name to a DataReader. See 47.11 ENTITY_NAME QosPolicy (DDS Extension). |
History |
Specifies how much data must to stored by Connext for the DataWriter or DataReader. This QosPolicy affects the 47.21 RELIABILITY QosPolicy as well as the 47.9 DURABILITY QosPolicy. See 47.12 HISTORY QosPolicy. |
LatencyBudget |
Suggestion to Connext on how much time is allowed to deliver data. See 47.13 LATENCYBUDGET QoS Policy. |
Liveliness |
Specifies and configures the mechanism that allows DataReaders to detect when DataWriters become disconnected or "dead." See 47.15 LIVELINESS QosPolicy. |
Property |
Stores name/value (string) pairs that can be used to configure certain parameters of Connext 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 47.19 PROPERTY QosPolicy (DDS Extension) . |
ReaderDataLifecycle |
Controls how a DataReader manages the lifecycle of the data that it has received. See 48.3 READER_DATA_LIFECYCLE QoS Policy. |
Reliability |
Specifies whether or not Connext will deliver data reliably. See 47.21 RELIABILITY QosPolicy. |
ResourceLimits |
Controls the amount of physical memory allocated for entities, if dynamic allocations are allowed, and how they occur. Also controls memory usage among different instance values for keyed topics. See 47.22 RESOURCE_LIMITS QosPolicy. |
Service |
Intended for use by RTI infrastructure services. User applications should not modify its value. See 47.23 SERVICE QosPolicy (DDS Extension). |
TimeBasedFilter |
Set by a DataReader to limit the number of new data values received over a period of time. See 48.4 TIME_BASED_FILTER QosPolicy. |
TransportMulticast |
Specifies the multicast address on which a DataReader wants to receive its data. Can specify a port number as well as a subset of the available transports with which to receive the multicast data. See 48.5 TRANSPORT_MULTICAST QosPolicy (DDS Extension). |
TransportPriority |
Set by a DataReader to tell Connext that the data being sent is a different "priority" than other data. See 47.26 TRANSPORT_PRIORITY QosPolicy. |
TransportSelection |
Allows you to select which physical transports a DataWriter or DataReader may use to send or receive its data. See 47.27 TRANSPORT_SELECTION QosPolicy (DDS Extension). |
TransportUnicast |
Specifies a subset of transports and port number that can be used by an Entity to receive data. See 47.28 TRANSPORT_UNICAST QosPolicy (DDS Extension). |
TypeConsistencyEnforcement |
Defines rules that determine whether the type used to publish a given data stream is consistent with that used to subscribe to it. See 48.6 TYPE_CONSISTENCY_ENFORCEMENT QosPolicy. |
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. Also controls whether padding bytes are set to 0 during serialization. See 47.29 TYPESUPPORT QosPolicy (DDS Extension). |
UserData |
Along with Topic Data QosPolicy and Group Data QosPolicy, used to attach a buffer of bytes to Connext's discovery meta-data. See 47.30 USER_DATA QosPolicy. |
For a DataReader to communicate with a DataWriter, their corresponding QosPolicies must be compatible. For QosPolicies that apply both to the DataWriter and the DataReader, the setting in the DataWriter is considered what the DataWriter “offers” and the setting in the DataReader is what the DataReader “requests.” Compatibility means that what is offered by the DataWriter equals or surpasses what is requested by the DataReader. See 42.1 QoS Requested vs. Offered Compatibility—the RxO Property.
Some of the policies may be changed after the DataReader has been created. This allows the application to modify the behavior of the DataReader while it is in use. To modify the QoS of an already-created DataReader, use the get_qos() and set_qos() operations on the DataReader. This is a general pattern for all Entities, described in 49.3 Changing the QoS for an Existing Entity.
40.9.1 Configuring QoS Settings when the DataReader is Created
As described in 40.1 Creating DataReaders, there are different ways to create a DataReader, depending on how you want to specify its QoS (with or without a QoS Profile).
- In Figure 40.1: Creating a DataReader with Default QosPolicies , there is an example of how to create a DataReader with default QosPolicies by using the special constant, DDS_DATAREADER_QOS_DEFAULT, which indicates that the default QoS values for a DataReader should be used. The default DataReader QoS values are configured in the Subscriber or DomainParticipant; you can change them with set_default_datareader_qos() or set_default_datareader_qos_with_profile(). Then any DataReaders created with the Subscriber will use the new default values. As described in 49. Configuring Qos Programmatically, this is a general pattern that applies to the construction of all Entities.
- To create a DataReader with non-default QoS without using a QoS Profile, see the example code in Figure 40.6: Creating a DataReader with Modified QosPolicies (not from a profile). It uses the Subscriber’s get_default_reader_qos() method to initialize a DDS_DataReaderQos structure. Then the policies are modified from their default values before the structure is used in the create_datareader() method.
- You can also create a DataReader and specify its QoS settings via a QoS Profile. To do so, you will call create_datareader_with_profile(), as seen in Figure 40.7: Creating a DataReader with a QoS Profile.
- If you want to use a QoS profile, but then make some changes to the QoS before creating the DataReader, call get_datawriter_qos_from_profile() and create_datawriter() as seen in Figure 40.8: Getting QoS Values from Profile, Changing QoS Values, Creating DataReader with Modified QoS Values.
For more information, see 31.1 Creating DataWriters and 50. Configuring QoS with XML.
Notes:
- The examples in this section use the Traditional C++ API; for examples in the Modern C++ API, see the sections "DataReader Use Cases," "Qos Use Cases," and "Qos Provider Use Cases" in the API Reference HTML documentation, under "Programming How-To's."
- In C, you must initialize the QoS structures before they are used, see 42.2 Special QosPolicy Handling Considerations for C.
Figure 40.6: Creating a DataReader with Modified QosPolicies (not from a profile)
DDS_DataReaderQos reader_qos;
// initialize reader_qos with default values subscriber->get_default_datareader_qos(reader_qos); // make QoS changes reader_qos.history.depth = 5; // Create the reader with modified qos DDSDataReader * reader = subscriber->create_datareader( topic, reader_qos, NULL, DDS_STATUS_MASK_NONE); if (reader == NULL) { // ... error } // narrow it for your specific data type FooDataReader* foo_reader = FooDataReader::narrow(reader);
Figure 40.7: Creating a DataReader with a QoS Profile
// Create the datareader DDSDataReader * reader = subscriber->create_datareader_with_profile( topic, “MyReaderLibrary”, “MyReaderProfile”, NULL, DDS_STATUS_MASK_NONE); if (reader == NULL) { // ... error }; // narrow it for your specific data type FooDataReader* foo_reader = FooDataReader::narrow(reader);
Figure 40.8: Getting QoS Values from Profile, Changing QoS Values, Creating DataReader with Modified QoS Values
DDS_DataReaderQos reader_qos;
// Get reader QoS from profile retcode = factory->get_datareader_qos_from_profile( reader_qos, “ReaderProfileLibrary”, “ReaderProfile”); if (retcode != DDS_RETCODE_OK) { // handle error } // Makes QoS changes reader_qos.history.depth = 5; DDSDataReader * reader = subscriber->create_datareader( topic, reader_qos, NULL, DDS_STATUS_MASK_NONE); if (participant == NULL) { // handle error }
40.9.2 Comparing QoS Values
The equals() operation compares two DataReader’s DDS_DataReaderQoS structures for equality. It takes two parameters for the two DataReader’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.
40.9.3 Changing QoS Settings After the DataReader has been Created
There are two ways to change an existing DataReader’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 40.9: Changing the QoS of Existing DataReader (without a QoS Profile). It retrieves the current values by calling the DataWriter’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 DataWriter has been enabled—this restriction is noted in the descriptions of the individual QosPolicies.
- You can also change a DataReader’s (and all other Entities’) QoS by using a QoS Profile and calling set_qos_with_profile(). For an example, see Figure 40.10: Changing the QoS of Existing DataReader with a QoS Profile . For more information, see 50. Configuring QoS with XML.
Note:
- In C, you must initialize the QoS structures before they are used, see 42.2 Special QosPolicy Handling Considerations for C.
Figure 40.9: Changing the QoS of Existing DataReader (without a QoS Profile)
DDS_DataReaderQos reader_qos;
// Get current QoS. if (datareader->get_qos(reader_qos) != DDS_RETCODE_OK) { // handle error } // Makes QoS changes here reader_qos.history.depth = 5; // Set the new QoS if (datareader->set_qos(reader_qos) != DDS_RETCODE_OK ) { // handle error }
Figure 40.10: Changing the QoS of Existing DataReader with a QoS Profile
retcode = reader->set_qos_with_profile(
“ReaderProfileLibrary”,”ReaderProfile”); if (retcode != DDS_RETCODE_OK) { // handle error }
40.9.4 Using a Topic’s QoS to Initialize a DataReader’s QoS
Several DataReader QosPolicies can also be found in the QosPolicies for Topics (see 18.1.3 Setting Topic QosPolicies). The QosPolicies set in the Topic do not directly affect the DataReaders (or DataWriters) that use that Topic. In many ways, some QosPolicies are a Topic-level concept, even though the DDS standard allows you to set different values for those policies for different DataWriters and DataReaders of the same Topic. Thus, the policies in the DDS_TopicQos structure exist as a way to help centralize and annotate the intended or suggested values of those QosPolicies. Connext does not check to see if the actual policies set for a DataReader is aligned with those set in the Topic to which it is bound.
There are many ways to use the QosPolicies’ values set in the Topic when setting the QosPolicies’ values in a DataReader. The most straightforward way is to get the values of policies directly from the Topic and use them in the policies for the DataReader, as shown in Figure 40.11: Copying Selected QoS from a Topic when Creating a DataReader.
Note:
- In C, you must initialize the QoS structures before they are used, see 42.2 Special QosPolicy Handling Considerations for C.
Figure 40.11: Copying Selected QoS from a Topic when Creating a DataReader
DDS_DataReaderQos reader_qos;
DDS_TopicQos topic_qos; // topic and publisher already created // get current QoS for the topic, default QoS for the reader if (topic->get_qos(topic_qos) != DDS_RETCODE_OK) { // handle error } if (publisher->get_default_datareader_qos(reader_qos) != DDS_RETCODE_OK) { // handle error } // Copy specific policies from topic QoS to reader QoS reader_qos.deadline = topic_qos.deadline; reader_qos.reliability = topic_qos.reliability; // Create the DataReader with the modified QoS DDSDataReader* reader = publisher->create_datareader(topic, reader_qos,NULL, DDS_STATUS_MASK_NONE);
You can use the Subscriber’s copy_from_topic_qos() operation to copy all of the common policies from the Topic QoS to a DataReader QoS. This is illustrated in Figure 40.12: Copying all QoS from a Topic when Creating a DataReader .
Figure 40.12: Copying all QoS from a Topic when Creating a DataReader
DDS_DataReaderQos reader_qos;
DDS_TopicQos topic_qos; // topic, publisher, reader_listener already created if (topic->get_qos(topic_qos) != DDS_RETCODE_OK) { // handle error } if (publisher->get_default_datareader_qos(reader_qos) != DDS_RETCODE_OK) { // handle error } // copy relevant QoS from topic into reader’s qos publisher->copy_from_topic_qos(reader_qos, topic_qos); // Optionally, modify policies as desired reader_qos.deadline.duration.sec = 1; reader_qos.deadline.duration.nanosec = 0; // Create the DataReader with the modified QoS DDSDataReader* reader = publisher->create_datareader(topic, reader_qos, reader_listener, DDS_STATUS_MASK_ALL);
The special macro, DDS_DATAREADER_QOS_USE_TOPIC_QOS, can be used to indicate that the DataReader should be created with the QoS that results from modifying the default DataReader QoS with the values specified by the Topic. See Figure 31.15: Combining Default Topic and DataWriter QoS (Option 1) and Figure 31.16: Combining Default Topic and DataWriter QoS (Option 2) for examples involving DataWriters. The same pattern applies to DataReaders.
For more information on the general use and manipulation of QosPolicies, see 49. Configuring Qos Programmatically.