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.
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 |
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 |
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:
(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.
For a DataWriter—a new DDS sample for the instance will replace the oldest DDS sample for the instance in the sending queue—only if the DDS sample being overwritten has been fully acknowledged as being received by all reliable DataReaders. If the oldest DDS sample for the instance has not been fully acknowledged, the write() operation trying to enter a new DDS sample for the instance into the sending queue will block (for the max_blocking_time specified in the RELIABLE 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.
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.
This QosPolicy cannot be modified after the Entity has been enabled.
There is no requirement that the publishing and subscribing sides use compatible values.
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