The DataWriter’s QosPolicies control its resources and behavior.
The DDS_DataWriterQos structure has the following format:
DDS_DataWriterQos struct { DDS_DurabilityQosPolicy durability; DDS_DurabilityServiceQosPolicy durability_service; 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_TransportPriorityQosPolicy transport_priority; DDS_LifespanQosPolicy lifespan; DDS_UserDataQosPolicy user_data; DDS_OwnershipQosPolicy ownership; DDS_OwnershipStrengthQosPolicy ownership_strength; DDS_WriterDataLifecycleQosPolicy writer_data_lifecycle; // extensions to the DDS standard: DDS_DataWriterResourceLimitsQosPolicy writer_resource_limits; DDS_DataWriterProtocolQosPolicy protocol; DDS_TransportSelectionQosPolicy transport_selection; DDS_TransportUnicastQosPolicy unicast; DDS_PublishModeQosPolicy publish_mode; DDS_PropertyQosPolicy property; DDS_ServiceQosPolicy service; DDS_BatchQosPolicy batch; DDS_MultiChannelQosPolicy multi_channel; DDS_AvailabilityQosPolicy availability; DDS_EntityNameQosPolicy publication_name; DDS_TypeSupportQosPolicy type_support; } DDS_DataWriterQos;
Note: set_qos() cannot always be used within a listener callback, see Restricted Operations in Listener Callbacks.
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: Availability QoS Policy and Collaborative DataWriters AVAILABILITY QosPolicy (DDS Extension) For Collaborative DataWriters, Availability specifies the group of DataWriters expected to collaboratively provide data and the timeouts that control when to allow data to be available that may skip DDS samples. For Required Subscriptions, Availability configures a set of Required Subscriptions on a DataWriter. |
Batch |
Specifies and configures the mechanism that allows Connext DDS to collect multiple DDS user data samples to be sent in a single network packet, to take advantage of the efficiency of sending larger packets and thus increase effective throughput. See BATCH QosPolicy (DDS Extension). |
DataWriterProtocol |
This QosPolicy configures the Connext DDS on-the-network protocol, RTPS. See DATA_WRITER_PROTOCOL QosPolicy (DDS Extension). |
DataWriterResourceLimits |
Controls how many threads can concurrently block on a write() call of this DataWriter. See DATA_WRITER_RESOURCE_LIMITS QosPolicy (DDS Extension). |
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. See DEADLINE QosPolicy. |
DestinationOrder |
Controls how Connext DDS 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 DESTINATION_ORDER QosPolicy. |
Durability |
Specifies whether or not Connext DDS will store and deliver data that were previously published to new DataReaders. See DURABILITY QosPolicy. |
DurabilityService |
Various settings to configure the external Persistence Service1Persistence Service is provided with the Connext DDS Professional, Evaluation, and Basic package types. used by Connext DDS for DataWriters with a Durability QoS setting of Persistent Durability. See DURABILITY SERVICE QosPolicy. |
EntityName |
Assigns a name to a DataWriter. See ENTITY_NAME QosPolicy (DDS Extension). |
History |
Specifies how much data must to stored by Connext DDS for the DataWriter or DataReader. This QosPolicy affects the RELIABILITY QosPolicy as well as the DURABILITY QosPolicy. See HISTORY QosPolicy. |
LatencyBudget |
Suggestion to Connext DDS on how much time is allowed to deliver data. See LATENCYBUDGET QoS Policy. |
Lifespan |
Specifies how long Connext DDS should consider data sent by an user application to be valid. See LIFESPAN QoS Policy. |
Liveliness |
Specifies and configures the mechanism that allows DataReaders to detect when DataWriters become disconnected or "dead." See LIVELINESS QosPolicy. |
MultiChannel |
Configures a DataWriter’s ability to send data on different multicast groups (addresses) based on the value of the data. See MULTI_CHANNEL QosPolicy (DDS Extension). |
Along with OwnershipStrength, specifies if DataReaders for a topic can receive data from multiple DataWriters at the same time. See OWNERSHIP QosPolicy. |
|
OwnershipStrength |
Used to arbitrate among multiple DataWriters of the same instance of a Topic when Ownership QosPolicy is EXCLUSIVE. See OWNERSHIP_STRENGTH QosPolicy. |
Partition |
Adds string identifiers that are used for matching DataReaders and DataWriters for the same Topic. See PARTITION QosPolicy. |
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) . |
PublishMode |
Specifies how Connext DDS sends application data on the network. By default, data is sent in the user thread that calls the DataWriter’s write() operation. However, this QosPolicy can be used to tell Connext DDS to use its own thread to send the data. See PUBLISH_MODE QosPolicy (DDS Extension). |
Reliability |
Specifies whether or not Connext DDS will deliver data reliably. See 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 RESOURCE_LIMITS QosPolicy. |
Service |
Intended for use by RTI infrastructure services. User applications should not modify its value. See SERVICE QosPolicy (DDS Extension). |
TransportPriority |
Set by a DataWriter to tell Connext DDS that the data being sent is a different "priority" than other data. See TRANSPORT_PRIORITY QosPolicy. |
TransportSelection |
Allows you to select which physical transports a DataWriter or DataReader may use to send or receive its data. See 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 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. Also controls whether padding bytes are set to 0 during serialization. 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. |
WriterDataLifeCycle |
Controls how a DataWriter handles the lifecycle of the instances (keys) that the DataWriter is registered to manage. See WRITER_DATA_LIFECYCLE QoS Policy. |
Many of the DataWriter QosPolicies also apply to DataReaders (see DataReaders). For a DataWriter to communicate with a DataReader, their QosPolicies must be compatible. Generally, for the QosPolicies that apply both to the DataWriter and the DataReader, the setting in the DataWriter is considered an “offer” and the setting in the DataReader is a “request.” Compatibility means that what is offered by the DataWriter equals or surpasses what is requested by the DataReader. Each policy’s description includes compatibility restrictions. For more information on compatibility, see QoS Requested vs. Offered Compatibility—the RxO Property.
Some of the policies may be changed after the DataWriter has been created. This allows the application to modify the behavior of the DataWriter while it is in use. To modify the QoS of an already-created DataWriter, use the get_qos() and set_qos() operations on the DataWriter. This is a general pattern for all Entities, described in Changing the QoS for an Existing Entity.
As described in Creating DataWriters, there are different ways to create a DataWriter, depending on how you want to specify its QoS (with or without a QoS Profile).
For more information, see Creating DataWriters and Configuring QoS with XML.
Figure 16 Creating a DataWriter with Modified QosPolicies (not from a profile)
DDS_DataWriterQos writer_qos;2Note: In C, you must initialize the QoS structures before they are used, see Special QosPolicy Handling Considerations for C. // initialize writer_qos with default values publisher->get_default_datawriter_qos(writer_qos); // make QoS changes writer_qos.history.depth = 5; // Create the writer with modified qos DDSDataWriter * writer = publisher->create_datawriter( topic, writer_qos, NULL, DDS_STATUS_MASK_NONE); if (writer == NULL) { // ... error } // narrow it for your specific data type FooDataWriter* foo_writer = FooDataWriter::narrow(writer);
Figure 17 Creating a DataWriter with a QoS Profile
// Create the datawriter DDSDataWriter * writer = publisher->create_datawriter_with_profile( topic, “MyWriterLibrary”, “MyWriterProfile”, NULL, DDS_STATUS_MASK_NONE); if (writer == NULL) { // ... error }; // narrow it for your specific data type FooDataWriter* foo_writer = FooDataWriter::narrow(writer);
Figure 18 Getting QoS Values from a Profile, Changing QoS Values, Creating a DataWriter with Modified QoS Values
DDS_DataWriterQos writer_qos;3Note: In C, you must initialize the QoS structures before they are used, see Special QosPolicy Handling Considerations for C. // Get writer QoS from profile retcode = factory->get_datawriter_qos_from_profile( writer_qos, “WriterProfileLibrary”, “WriterProfile”); if (retcode != DDS_RETCODE_OK) { // handle error } // Makes QoS changes writer_qos.history.depth = 5; DDSDataWriter * writer = publisher->create_datawriter( topic, writer_qos, NULL, DDS_STATUS_MASK_NONE); if (participant == NULL) { // handle error }
The equals() operation compares two DataWriter’s DDS_DataWriterQoS structures for equality. It takes two parameters for the two DataWriter’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.
There are two ways to change an existing DataWriter’s QoS after it is has been created—again depending on whether or not you are using a QoS Profile.
Figure 19 Changing the QoS of an Existing DataWriter (without a QoS Profile)
DDS_DataWriterQos writer_qos;4Note: In C, you must initialize the QoS structures before they are used, see Special QosPolicy Handling Considerations for C. // Get current QoS. if (datawriter->get_qos(writer_qos) != DDS_RETCODE_OK) { // handle error } // Makes QoS changes here writer_qos.history.depth = 5; // Set the new QoS if (datawriter->set_qos(writer_qos) != DDS_RETCODE_OK ) { // handle error }
Figure 20 Changing the QoS of an Existing DataWriter with a QoS Profile
retcode = writer->set_qos_with_profile( “WriterProfileLibrary”,”WriterProfile”); if (retcode != DDS_RETCODE_OK) { // handle error }
Several DataWriter QosPolicies can also be found in the QosPolicies for Topics (see Setting Topic QosPolicies). The QosPolicies set in the Topic do not directly affect the DataWriters (or DataReaders) 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 DDS does not check to see if the actual policies set for a DataWriter 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 DataWriter. The most straightforward way is to get the values of policies directly from the Topic and use them in the policies for the DataWriter, as shown in Figure 21.
Figure 21 Copying Selected QoS from a Topic when Creating a DataWriter
DDS_DataWriterQos writer_qos;5Note: In C, you must initialize the QoS structures before they are used, see Special QosPolicy Handling Considerations for C. DDS_TopicQos topic_qos; // topic and publisher already created // get current QoS for the topic, default QoS for the writer if (topic->get_qos(topic_qos) != DDS_RETCODE_OK) { // handle error } if (publisher->get_default_datawriter_qos(writer_qos) != DDS_RETCODE_OK) { // handle error } // Copy specific policies from topic QoS to writer QoS writer_qos.deadline = topic_qos.deadline; writer_qos.reliability = topic_qos.reliability; // Create the DataWriter with the modified QoS DDSDataWriter* writer = publisher->create_datawriter(topic, writer_qos,NULL, DDS_STATUS_MASK_NONE);
You can use the Publisher’s copy_from_topic_qos() operation to copy all of the common policies from the Topic QoS to a DataWriter QoS. This is illustrated in Figure 22.
Figure 22 Copying all QoS from a Topic when Creating a DataWriter
DDS_DataWriterQos writer_qos;6Note: In C, you must initialize the QoS structures before they are used, see Special QosPolicy Handling Considerations for C. DDS_TopicQos topic_qos; // topic, publisher, writer_listener already created if (topic->get_qos(topic_qos) != DDS_RETCODE_OK) { // handle error } if (publisher->get_default_datawriter_qos(writer_qos) != DDS_RETCODE_OK) { // handle error } // copy relevant QoS from topic into writer’s qos publisher->copy_from_topic_qos(writer_qos, topic_qos); // Optionally, modify policies as desired writer_qos.deadline.duration.sec = 1; writer_qos.deadline.duration.nanosec = 0; // Create the DataWriter with the modified QoS DDSDataWriter* writer = publisher->create_datawriter(topic, writer_qos, writer_listener, DDS_STATUS_MASK_ALL);
In another design pattern, you may want to start with the default QoS values for a DataWriter and override them with the QoS values of the Topic. Figure 23 gives an example of how to do this.
Because this is a common pattern, Connext DDS provides a special macro, DDS_DATAWRITER_QOS_USE_TOPIC_QOS, that can be used to indicate that the DataWriter should be created with the set of QoS values that results from modifying the default DataWriter QosPolicies with the QoS values specified by the Topic. Figure 24 shows how the macro is used.
The code fragments shown in Figure 23 and Figure 24 result in identical QoS settings for the created DataWriter.
Figure 23 Combining Default Topic and DataWriter QoS (Option 1)
DDS_DataWriterQos writer_qos;7Note: In C, you must initialize the QoS structures before they are used, see Special QosPolicy Handling Considerations for C. DDS_TopicQos topic_qos; // topic, publisher, writer_listener already created if (topic->get_qos(topic_qos) != DDS_RETCODE_OK) { // handle error } if (publisher->get_default_datawriter_qos(writer_qos) != DDS_RETCODE_OK) { // handle error } if (publisher->copy_from_topic_qos(writer_qos, topic_qos) != DDS_RETCODE_OK) { // handle error } // Create the DataWriter with the combined QoS DDSDataWriter* writer = publisher->create_datawriter(topic, writer_qos, writer_listener,DDS_STATUS_MASK_ALL);
Figure 24 Combining Default Topic and DataWriter QoS (Option 2)
// topic, publisher, writer_listener already created DDSDataWriter* writer = publisher->create_datawriter (topic, DDS_DATAWRITER_QOS_USE_TOPIC_QOS, writer_listener, DDS_STATUS_MASK_ALL);
For more information on the general use and manipulation of QosPolicies, see Getting, Setting, and Comparing QosPolicies.
© 2016 RTI