HISTORY QosPolicy

This QosPolicy configures the number of DDS samples that Connext DDS will store locally for DataWriters and DataReaders. For keyed Topics, this QosPolicy applies on a per instance basis, so that Connext DDS will attempt to store the configured value of DDS samples for every instance (see DDS Samples, Instances, and Keys for a discussion of keys and instances).

It includes the members seen in DDS_HistoryQosPolicy. For defaults and valid ranges, please refer to the API Reference HTML documentation.

DDS_HistoryQosPolicy

Type

Field Name

Description

DDS_HistoryQos-PolicyKind

kind

DDS_KEEP_LAST_HISTORY_QOS: keep the last depth number of DDS samples per instance.

DDS_KEEP_ALL_HISTORY_QOS: keep all DDS samples.1Connext DDS will store up to the value of the max_samples_per_instance parameter of the RESOURCE_LIMITS QosPolicy.

DDS_Long

depth

If kind = DDS_KEEP_LAST_HISTORY_QOS, this is how many DDS samples to keep per instance.2depth must be <= max_samples_per_instance parameter of the RESOURCE_LIMITS QosPolicy

if kind = DDS_KEEP_ALL_HISTORY_QOS, this value is ignored.

DDS_RefilterQos-PolicyKind

refilter

Specifies how a DataWriter should handle previously written DDS samples for a new DataReader.

When a new DataReader matches a DataWriter, the DataWriter can be configured to perform content-based filtering on previously written DDS samples stored in the DataWriter queue for the new DataReader.

May be:

  • DDS_NONE_REFILTER_QOS Do not filter existing DDS samples for a new DataReader. The DataReader will do the filtering.

  • DDS_ALL_REFILTER_QOS Filter all existing DDS samples for a newly matched DataReader.

  • DDS_ON_DEMAND_REFILTER_QOS Filter existing DDS samples only when they are requested by the DataReader.

(An extension to the DDS standard.)

The kind determines whether or not to save a configured number of DDS samples or all DDS samples. It can be set to either of the following:

The above descriptions say “attempts to keep” because the actual number of DDS samples kept is subject to the limitations imposed by the RESOURCE_LIMITS QosPolicy. All of the DDS samples of all instances of a Topic share a single physical queue that is allocated for a DataWriter or DataReader. The size of this queue is configured by the RESOURCE_LIMITS QosPolicy. If there are many difference instances for a Topic, it is possible that the physical queue may run out of space before the number of DDS samples reaches the depth for all instances.

In the KEEP_ALL case, Connext DDS can only keep as many DDS samples for a Topic (independent of instances) as the size of the allocated queue. Connext DDS may or may not allocate more memory when the queue is filled, depending on the settings in the RESOURCE_LIMITS QoSPolicy of the DataWriter or DataReader.

This QosPolicy interacts with the RELIABILITY QosPolicy by controlling whether or not Connext DDS guarantees that ALL of the data sent is received or if only the last N data values sent are guaranteed to be received (a reduced level of reliability using the KEEP_LAST setting). However, the physical sizes of the send and receive queues are not controlled by the History QosPolicy. The memory allocation for the queues is controlled by the RESOURCE_LIMITS QosPolicy. Also, the amount of data that is sent to new DataReaders who have configured their DURABILITY QosPolicy to receive previously published data is controlled by the History QosPolicy.

What happens when the physical queue is filled depends both on the setting for the HISTORY QosPolicy as well as the RELIABILITY QosPolicy.

Although you can set the HISTORY QosPolicy on Topics, its value can only be used to initialize the HISTORY QosPolicies of either a DataWriter or DataReader. It does not directly affect the operation of Connext DDS, see Setting Topic QosPolicies.

Example

To achieve strict reliability, you must (1) set the DataWriter’s and DataReader’s HISTORY QosPolicy to KEEP_ALL, and (2) set the DataWriter’s and DataReader’s RELIABILITY QosPolicy to RELIABLE.

See Reliable Communications for a complete discussion on Connext DDS’s reliable protocol.

See Controlling Queue Depth with the History QosPolicy.

Properties

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

There is no requirement that the publishing and subscribing sides use compatible values.

Related QosPolicies

Applicable Entities

System Resource Considerations

While this QosPolicy does not directly affect the system resources used by Connext DDS, the RESOURCE_LIMITS QosPolicy that must be used in conjunction with the HISTORY QosPolicy will affect the amount of memory that Connext DDS will allocate for a DataWriter or DataReader.

© 2018 RTI