47.12 HISTORY QosPolicy

This QosPolicy configures the number of DDS samples that Connext will store locally for DataWriters and DataReaders. For reliable DataWriters, the HISTORY QosPolicy configures the reliability window, or the number of samples that are kept until all matching DataReaders have fully-acknowledged the samples. For keyed Topics, this QosPolicy applies on a per instance basis, so that Connext will attempt to store the configured value of DDS samples for every instance (see 8. DDS Samples, Instances, and Keys for a discussion of keys and instances).

This QoS policy includes the members seen in Table 47.23 DDS_HistoryQosPolicy. For defaults and valid ranges, please refer to the API Reference HTML documentation.

Table 47.23 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. Connext will store up to the value of the max_samples_per_instance parameter in the 47.22 RESOURCE_LIMITS QosPolicy.

For DataWriters, the samples are kept only until either they are fully acknowledged by all matching DataReaders or they are replaced. See 31.8.2 write() behavior with KEEP_LAST and KEEP_ALL for more information about when a sample may be replaced in the DataWriter queue.

DDS_Long

depth

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

if kind = DDS_KEEP_ALL_HISTORY_QOS, this value is ignored.

The kind determines whether or not to save a configured number of DDS samples or all DDS samples. In either case, when using a Reliable 47.21 RELIABILITY QosPolicy, the samples are kept until they are fully acknowledged by all matching DataReaders. Once a sample is fully acknowledged, it is removed from the DataWriter's queue, unless it needs to be kept for durability purposes. (See 47.9 DURABILITY QosPolicy). The HISTORY QoS Policy kind can be set to either of the following:

  • DDS_KEEP_LAST_HISTORY_QOS. Connext attempts to keep the latest values of the data-instance and discard the oldest ones when the limit as set by the depth parameter is reached; new data will overwrite the oldest data in the queue. Thus the queue acts like a circular buffer of length depth. Invalid samples are samples representing the disposal or unregistration of an instance. There is only ever 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. How invalid samples affect the history depth differs for DataReaders and DataWriters:
    • For a DataWriter: Connext attempts to keep the most recent depth DDS samples of each instance (identified by a unique key) managed by the DataWriter. Invalid samples count towards the depth and may replace other DDS samples currently in the DataWriter queue.
    • For a DataReader: Connext attempts to keep the most recent depth DDS samples received for each instance (identified by a unique key) until the application takes them via the DataReader's take() operation. See 41.3 Accessing DDS Data Samples with Read or Take for a discussion of the difference between read() and take(). Invalid samples do not count towards the depth and will not replace other DDS samples currently in the DataReader queue.
  • DDS_KEEP_ALL_HISTORY_QOS. Connext attempts to keep all of the DDS samples of a Topic.
    • For a DataWriter: Connext attempts to keep all DDS samples published by the DataWriter.
    • For a DataReader: Connext attempts to keep all DDS samples received by the DataReader for a Topic (both keyed and non-keyed) until the application takes them via the DataReader's take() operation. See 41.3 Accessing DDS Data Samples with Read or Take for a discussion of the difference between read() and take().
    • The value of the depth parameter is ignored.

The above descriptions say “attempts to keep” because the actual number of DDS samples kept is subject to the limitations imposed by the 47.22 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 different 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 can only keep as many DDS samples for a Topic (independent of instances) as the size of the allocated queue. Connext 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 47.21 RELIABILITY QosPolicy by controlling whether or not Connext 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 47.22 RESOURCE_LIMITS QosPolicy.

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

  • DDS_KEEP_LAST_HISTORY_QOS
    • If RELIABILITY is BEST_EFFORT: When the number of DDS samples for an instance in the queue reaches the value of depth, a new DDS sample for the instance will replace the oldest DDS sample for the instance in the queue.
    • If RELIABILITY is RELIABLE: When the number of DDS samples for an instance in the queue reaches the value of depth, a new DDS sample for the instance will replace the oldest DDS sample for the instance in the queue—even if the DDS sample being overwritten has not been fully acknowledged as being received by all reliable DataReaders. This implies that the discarded DDS sample may be lost (with the reason LOST_BY_WRITER) by some reliable DataReaders. Thus, when using the KEEP_LAST setting, strict reliability is not guaranteed. See 32. Reliability Models for Sending Data for a complete discussion on Connext’s reliable protocol.
  • DDS_KEEP_ALL_HISTORY_QOS
    • If RELIABILITY is BEST_EFFORT: For a DataWriter, if the number of DDS samples for an instance in the queue reaches the value of the 47.22 RESOURCE_LIMITS QosPolicy’s max_samples_per_instance field, a new DDS sample for the instance will replace the oldest DDS sample for the instance in the queue (regardless of instance). For a DataReader, a new DDS sample received by the DataReader when this resource limit is exceeded will be lost with the reason DDS_LOST_BY_SAMPLES_PER_INSTANCE_LIMIT.
    • If RELIABILITY is RELIABLE: When the number of DDS samples for an instance in the queue reaches the value of the 47.22 RESOURCE_LIMITS QosPolicy’s max_samples_per_instance field, then:
      • 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).
      • For a DataReader: max_samples_per_instance represents the maximum number of DDS samples of any one instance that are stored in the DataReader output queue—that is, the queue from which the application takes/reads samples. Therefore, when max_samples_per_instance is hit, the DataWriter samples will be rejected. They will not be moved to the DataReader output queue. They will stay in the DataWriter's remote writer queue until there is space for them in the DataReader output queue (until the samples in the DataReader output queue are taken). On a reliable DataReader, there is one remote writer queue for each DataWriter that matches the DataReader. The remote writer queue size is configurable with the resource limit reader_qos.reader_resource_limit.max_samples_per_remote_writer (see 48.2 DATA_READER_RESOURCE_LIMITS QosPolicy (DDS Extension)).

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, see 18.1.3 Setting Topic QosPolicies.

47.12.1 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 32. Reliability Models for Sending Data for a complete discussion on Connext’s reliable protocol.

See 32.4.3 Controlling Queue Depth with the History QosPolicy.

It is possible to configure the reliability window (the number of samples kept in the queue for reliability purposes) separately from the durability window (the number of samples kept in the DataWriter queue for late-joining DataReaders). This allows an application to achieve the level of reliability that is required and still only deliver a subset of data to late-joining DataReaders when using a non-VOLATILE 47.9 DURABILITY QosPolicy. Figure 47.1: History Depth and Durability Depth shows the relationship between History depth and Durability writer_depth.

Figure 47.1: History Depth and Durability Depth

The History depth determines how many samples to keep for reliability purposes (for example, for redelivering to DataReaders that haven’t acknowledged them yet). The 47.9 DURABILITY QosPolicy writer_depth determines what subset of those samples to deliver to late-joining DataReaders.

47.12.2 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.

47.12.3 Related QosPolicies

47.12.4 Applicable Entities

47.12.5 System Resource Considerations

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