|
RTI Connext C API Version 7.3.0
|
Specifies the behavior of RTI Connext in the case where the value of a sample changes (one or more times) before it can be successfully communicated to one or more existing subscribers. More...
Data Fields | |
| DDS_HistoryQosPolicyKind | kind |
| Specifies the kind of history to be kept. More... | |
| DDS_Long | depth |
Specifies the number of samples per instance to be kept, when the kind is DDS_KEEP_LAST_HISTORY_QOS. More... | |
Specifies the behavior of RTI Connext in the case where the value of a sample changes (one or more times) before it can be successfully communicated to one or more existing subscribers.
This QoS policy specifies how much data must to stored by RTI Connext for a DDS_DataWriter or DDS_DataReader. It controls whether RTI Connext should deliver only the most recent value, attempt to deliver all intermediate values, or do something in between.
On the publishing side, this QoS policy controls the samples that should be maintained by the DDS_DataWriter on behalf of existing DDS_DataReader entities. The behavior with regards to a DDS_DataReader entities discovered after a sample is written is controlled by the DURABILITY policy.
On the subscribing side, this QoS policy controls the samples that should be maintained until the application "takes" them from RTI Connext.
This policy controls the behavior of RTI Connext when the value of an instance changes before it is finally communicated to DDS_DataReader entities.
When a DDS_DataWriter sends data, or a DDS_DataReader receives data, the data sent or received is stored in a cache whose contents are controlled by this QoS policy. This QoS policy interacts with DDS_ReliabilityQosPolicy by controlling whether RTI Connext guarantees that all of the sent data is received (DDS_KEEP_ALL_HISTORY_QOS) or if only the last N data values sent are guaranteed to be received (DDS_KEEP_LAST_HISTORY_QOS)–this is a reduced level of reliability.
The amount of data that is sent to new DataReaders who have configured their DDS_DurabilityQosPolicy to receive previously published data is controlled by DDS_DurabilityQosPolicy::writer_depth, not by the History QoS policy.
Note that the History QoS policy does not control the physical sizes of the send and receive queues. The memory allocation for the queues is controlled by the DDS_ResourceLimitsQosPolicy.
If kind is DDS_KEEP_LAST_HISTORY_QOS (the default), then RTI Connext will only attempt to keep the latest values of the instance and discard the older ones. In this case, the value of depth regulates the maximum number of values (up to and including the most current one) RTI Connext will maintain and deliver until the samples are fully acknowledged. After N values have been sent or received, any new data will overwrite the oldest data in the queue. Thus the queue acts like a circular buffer of length N.
For keyed-data, there is different behavior on the publishing and subscribing sides associated with how invalid samples representing the disposal of or unregistration from an instance affect history.
On the publishing side, unregistering from or disposing of an instance creates an invalid sample that is accounted for in the history depth. This means that an invalid sample may replace a value that is currently being stored in the writer queue.
On the subscribing side, however, invalid samples do not count towards history depth and will not replace a value that is being stored in the reader queue.
On both the publishing and subscribing sides, there can only ever be one invalid sample per-instance and that one sample can be in different states depending on whether the instance has been disposed, unregistered, or both.
The default (and most common setting) for depth is 1, indicating that only the most recent value should be delivered.
If kind is DDS_KEEP_ALL_HISTORY_QOS, then RTI Connext will attempt to maintain and deliver all the values of the instance to existing subscribers. The resources that RTI Connext can use to keep this history are limited by the settings of the RESOURCE_LIMITS. If the limit is reached, then the behavior of RTI Connext will depend on the RELIABILITY. If the Reliability kind is DDS_BEST_EFFORT_RELIABILITY_QOS, then the old values will be discarded. If Reliability kind is RELIABLE, then RTI Connext will block the DDS_DataWriter until it can deliver the necessary old values to all subscribers.
This QoS policy's depth must be consistent with the RESOURCE_LIMITS max_samples_per_instance. For these two QoS to be consistent, they must verify that depth <= max_samples_per_instance.
| DDS_HistoryQosPolicyKind DDS_HistoryQosPolicy::kind |
Specifies the kind of history to be kept.
For DataWriters, the samples are only kept either until they are fully acknowledged by all matching DataReaders or until they are replaced or removed. Samples can be replaced or removed for a number of reasons, including but not limited to DDS_LifespanQosPolicy expiration, replacement because the DDS_HistoryQosPolicy::depth has been exceeded, or one of the DDS_ResourceLimitsQosPolicy settings has been exceeded.
[default] DDS_KEEP_LAST_HISTORY_QOS
| DDS_Long DDS_HistoryQosPolicy::depth |
Specifies the number of samples per instance to be kept, when the kind is DDS_KEEP_LAST_HISTORY_QOS.
If a value other than 1 (the default) is specified, it should be consistent with the settings of the RESOURCE_LIMITS policy. That is:
depth <= DDS_ResourceLimitsQosPolicy::max_samples_per_instance
When the kind is DDS_KEEP_ALL_HISTORY_QOS, the depth has no effect. Its implied value is infinity (in practice limited by the settings of the RESOURCE_LIMITS policy).
When a DataWriter responds to a TopicQuery, the samples that are evaluated against the TopicQuery filter are only those samples that fall within the DDS_DurabilityQosPolicy::writer_depth, not this depth.
[default] 1
[range] [1,100 million], <= DDS_ResourceLimitsQosPolicy::max_samples_per_instance