DURABILITY QosPolicy

47.9 DURABILITY QosPolicy

Because the publish-subscribe paradigm is connectionless, applications can create publications and subscriptions in any way they choose. As soon as a matching pair of DataWriters and DataReaders exist, the data published by the DataWriter will be delivered to the DataReader. However, a DataWriter may publish data before a DataReader has been created. For example, before you subscribe to a magazine, there have been past issues that were published.

The DURABILITY QosPolicy controls whether or not, and how, published DDS samples are stored by the DataWriter application for DataReaders that are found after the DDS samples were initially written. DataReaders use this QoS to request DDS samples that were published before the DataReaders were created. The analogy is for a new subscriber to a magazine to ask for issues that were published in the past. These are known as ‘historical’ DDS data samples. (Reliable DataReaders may wait for these historical DDS samples, see 40.5 Checking DataReader Status and StatusConditions.)

This QosPolicy can be used to help ensure that DataReaders get all data that was sent by DataWriters, regardless of when it was sent. This QosPolicy can increase system tolerance to failure conditions.

The 47.12 HISTORY QosPolicy controls how many samples the DataWriter stores for repair to currently matched DataReaders. The DURABILITY QosPolicy controls how many samples the DataWriter stores for sending to late-joining DataReaders (DataReaders that are found after the samples were initially written). See Figure 47.1: History Depth and Durability Depth.

The possible settings for this QoS are:

DDS_VOLATILE_DURABILITY_QOS

Connext is not required to send and will not deliver any DDS data samples to DataReaders that are discovered after the DDS samples were initially published.
DDS_TRANSIENT_LOCAL_DURABILITY_QOS

Connext will store and send previously published DDS samples for delivery to newly discovered DataReaders as long as the DataWriter still exists. For this setting to be effective, you must also set the 47.21 RELIABILITY QosPolicy kind to Reliable (not Best Effort). Which particular DDS samples are kept depends on other QoS settings such as 47.12 HISTORY QosPolicy and 47.22 RESOURCE_LIMITS QosPolicy.
DDS_TRANSIENT_DURABILITY_QOS

Connext will store previously published DDS samples in memory using Persistence Service, which will send the stored data to newly discovered DataReaders. Which particular DDS samples are kept and sent by Persistence Service depends on the 47.12 HISTORY QosPolicy and 47.22 RESOURCE_LIMITS QosPolicy of the Persistence Service DataWriters. These QosPolicies can be configured in the Persistence Service configuration file or through the 47.10 DURABILITY SERVICE QosPolicy of the DataWriters configured with DDS_TRANSIENT_DURABILITY_QOS.
DDS_PERSISTENT_DURABILITY_QOS

Connext will store previously published DDS samples in permanent storage, like a disk, using Persistence Service, which will send the stored data to newly discovered DataReaders. Which particular DDS samples are kept and sent by Persistence Service depends on the 47.12 HISTORY QosPolicy and 47.22 RESOURCE_LIMITS QosPolicy in the Persistence Service DataWriters. These QosPolicies can be configured in the Persistence Service configuration file or through the 47.10 DURABILITY SERVICE QosPolicy of the DataWriters configured with DDS_PERSISTENT_DURABILITY_QOS.

This QosPolicy includes the members in Table 47.19 DDS_DurabilityQosPolicy. For default settings, please refer to the API Reference HTML documentation.

Table 47.19 DDS_DurabilityQosPolicy
Type	Field Name	Description
DDS_DurabilityQosPolicyKind	kind	DDS_VOLATILE_DURABILITY_QOS: Do not save or deliver historical DDS samples. DDS_TRANSIENT_LOCAL_DURABILITY_QOS: Save and deliver historical DDS samples if the DataWriter still exists. DDS_TRANSIENT_DURABILITY_QOS: Save and deliver historical DDS samples using Persistence Service to store samples in volatile memory. DDS_PERSISTENCE_DURABILITY_QOS: Save and deliver historical DDS samples using Persistence Service to store samples in non-volatile memory.
DDS_Long	writer_depth	How many DDS samples are stored per instance by the DataWriter application for sending to late-joining DataReaders (DataReaders that are found after the DDS samples were initially written). The default value, AUTO, makes this parameter equal to the following: History depth in the 47.12 HISTORY QosPolicy if the History kind is KEEP_LAST. max_samples_per_instance in the 47.22 RESOURCE_LIMITS QosPolicy if the History kind is KEEP_ALL. The writer_depth must be <= to the History depth in the HISTORY QosPolicy if the History kind is KEEP_LAST. writer_depth applies only to non-volatile DataWriters (those for which the kind is DDS_TRANSIENT_LOCAL_DURABILITY_QOS, DDS_TRANSIENT_DURABILITY_QOS, or DDS_PERSISTENCE_DURABILITY_QOS). writer_depth set on the DataReader side will be ignored.
DDS_Boolean	direct_ communication	Whether or not a TRANSIENT or PERSISTENT DataReader should receive DDS samples directly from a TRANSIENT or PERSISTENT DataWriter. When TRUE, a TRANSIENT or PERSISTENT DataReaderwill receive DDS samples directly from the original DataWriter. The DataReadermay also receive DDS samples from Persistence Service, but the duplicates will be filtered by the middleware. When FALSE, a TRANSIENT or PERSISTENT DataReader will receive DDS samples only from the DataWriter created by Persistence Service. This ‘relay communication’ pattern provides a way to guarantee eventual consistency. See 21.5.1 RTI Persistence Service. This field only applies to DataReaders.

Information durability can be combined with required subscriptions in order to guarantee that DDS samples are delivered to a set of required subscriptions. For additional details on required subscriptions see 31.13 Required Subscriptions and 47.1 AVAILABILITY QosPolicy (DDS Extension).

A DataWriter will keep at most History.depth samples per instance until they are fully acknowledged. Samples outside of the Durability.writer_depth for an instance will be removed once they are fully acknowledged. Only the most recent Durability.writer_depth samples per instance will be kept by the DataWriter for delivery to late-joining non-volatile DataReaders.

When writer_depth is used in combination with batching, it acts as a minimum number of samples that will be kept per instance, rather than a maximum. Any batch that contains a sample that falls within the writer_depth of the instance to which it belongs will be sent to late-joining DataReaders. This means that batches may be sent that contain samples from other instances, or the same instance, that fall outside of the writer_depth for the instance to which they belong. For example, if the writer_depth is set to 1 and a batch with two samples for the same instance is written, then when a late-joining DataReader is discovered, the DataWriter will send the batch containing two samples for the same instance to the DataReader.

47.9.1 Example

Suppose you have a DataWriter that sends data sporadically and its DURABILITY kind is set to VOLATILE. If a new DataReader joins the system, it won’t see any data until the next time that write() is called on the DataWriter. If you want the DataReader to receive any data that is valid, old or new, both sides should set their DURABILITY kind to TRANSIENT_LOCAL. This will ensure that the DataReader gets some of the previous DDS samples immediately after it is enabled.

47.9.2 Properties

This QosPolicy cannot be modified after the Entity has been created.

The DataWriter and DataReader must use compatible settings for this QosPolicy. To be compatible, the DataWriter and DataReader must use one of the valid combinations shown in Table 47.20 Valid Combinations of Durability ‘kind’.

If this QosPolicy is found to be incompatible, the ON_OFFERED_INCOMPATIBLE_QOS and ON_REQUESTED_INCOMPATIBLE_QOS statuses will be modified and the corresponding Listeners called for the DataWriter and DataReader respectively.

Table 47.20 Valid Combinations of Durability ‘kind’
		DataReader requests:
		VOLATILE	TRANSIENT_LOCAL	TRANSIENT	PERSISTENT
DataWriter offers:	VOLATILE	compatible	incompatible	incompatible	incompatible
	TRANSIENT_ LOCAL	compatible	compatible	incompatible	incompatible
	TRANSIENT	compatible	compatible	compatible	incompatible
	PERSISTENT	compatible	compatible	compatible	compatible

47.9.3 Related QosPolicies

47.9.4 Applicable Entities

47.9.5 System Resource Considerations

Using this policy with a setting other than VOLATILE will cause Connext to use CPU and network bandwidth to send old DDS samples to matching, newly discovered DataReaders. The actual amount of resources depends on the total size of data that needs to be sent.

The maximum number of DDS samples that will be kept on the DataWriter’s queue for late-joiners and/or required subscriptions is determined by max_samples in RESOURCE_LIMITS Qos Policy.

System Resource Considerations With Required Subscriptions

By default, when TRANSIENT_LOCAL durability is used in combination with required subscriptions, a DataWriter configured with KEEP_ALL in the 47.12 HISTORY QosPolicy will keep the DDS samples in its cache until they are acknowledged by all the required subscriptions. (For additional details, see 31.13 Required Subscriptions.) After the DDS samples are acknowledged by the required subscriptions they will be marked as reclaimable, but they will not be purged from the DataWriter’s queue until the DataWriter needs these resources for new DDS samples. This may lead to a non efficient resource utilization, specially when max_samples is high or even UNLIMITED.

The DataWriter’s behavior can be changed to purge DDS samples after they have been acknowledged by all the active/matching DataReaders and all the required subscriptions configured on the DataWriter. To do so, set the dds.data_writer.history.purge_samples_after_acknowledgment property to 1 (see 47.19 PROPERTY QosPolicy (DDS Extension) ).

See 31.13 Required Subscriptions.