HistoryQosPolicy Class Reference

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

Inheritance diagram for HistoryQosPolicy:

Public Attributes
HistoryQosPolicyKind	kind
	Specifies the kind of history to be kept.
int	depth
	Specifies the number of samples to be kept, when the kind is com.rti.dds.infrastructure.HistoryQosPolicyKind.HistoryQosPolicyKind.KEEP_LAST_HISTORY_QOS.
RefilterQosPolicyKind	refilter
	<<eXtension>> Specifies how a writer should handle previously written samples to a new reader.
Public Attributes inherited from QosPolicy
final QosPolicyId_t	id
	The ID of this QoS policy.
final String	policy_name
	The name of this QoS policy.

Additional Inherited Members
Public Member Functions inherited from Struct
abstract boolean	equals (Object obj)
abstract int	hashCode ()
String	toString ()
Protected Member Functions inherited from Struct
	Struct ()
abstract void	pull_from_nativeI (long native_status)
abstract void	push_to_nativeI (long native_status)

Detailed Description

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 com.rti.dds.publication.DataWriter or com.rti.dds.subscription.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 com.rti.dds.publication.DataWriter on behalf of existing com.rti.dds.subscription.DataReader entities. The behavior with regards to a com.rti.dds.subscription.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.

Entity:

com.rti.dds.topic.Topic, com.rti.dds.subscription.DataReader, com.rti.dds.publication.DataWriter

Properties:

RxO = NO
Changeable = UNTIL ENABLE

See Also

com.rti.dds.infrastructure.ReliabilityQosPolicy

com.rti.dds.infrastructure.HistoryQosPolicy

Usage

This policy controls the behavior of RTI Connext when the value of an instance changes before it is finally communicated to com.rti.dds.subscription.DataReader entities.

When a com.rti.dds.publication.DataWriter sends data, or a com.rti.dds.subscription.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 com.rti.dds.infrastructure.ReliabilityQosPolicy by controlling whether RTI Connext guarantees that all of the sent data is received (com.rti.dds.infrastructure.HistoryQosPolicyKind.HistoryQosPolicyKind.KEEP_ALL_HISTORY_QOS) or if only the last N data values sent are guaranteed to be received (com.rti.dds.infrastructure.HistoryQosPolicyKind.HistoryQosPolicyKind.KEEP_ALL_HISTORY_QOS)–this is a reduced level of reliability.

The amount of data that is sent to new DataReaders who have configured their com.rti.dds.infrastructure.DurabilityQosPolicy to receive previously published data is also controlled 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 com.rti.dds.infrastructure.ResourceLimitsQosPolicy.

If kind is com.rti.dds.infrastructure.HistoryQosPolicyKind.HistoryQosPolicyKind.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. 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.

The default (and most common setting) for depth is 1, indicating that only the most recent value should be delivered.

If kind is com.rti.dds.infrastructure.HistoryQosPolicyKind.HistoryQosPolicyKind.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 com.rti.dds.infrastructure.ReliabilityQosPolicyKind.ReliabilityQosPolicyKind.BEST_EFFORT_RELIABILITY_QOS, then the old values will be discarded. If Reliability kind is RELIABLE, then RTI Connext will block the com.rti.dds.publication.DataWriter until it can deliver the necessary old values to all subscribers.

If refilter is com.rti.dds.infrastructure.RefilterQosPolicyKind.NONE_REFILTER_QOS, then samples written before a DataReader is matched to a DataWriter are not refiltered by the DataWriter.

If refilter is com.rti.dds.infrastructure.RefilterQosPolicyKind.ALL_REFILTER_QOS, then all samples written before a DataReader is matched to a DataWriter are refiltered by the DataWriter when the DataReader is matched.

If refilter is com.rti.dds.infrastructure.RefilterQosPolicyKind.ON_DEMAND_REFILTER_QOS, then a DataWriter will only refilter samples that a DataReader requests.

Consistency

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.

See Also

com.rti.dds.infrastructure.ResourceLimitsQosPolicy

Member Data Documentation

HistoryQosPolicyKind kind

Specifies the kind of history to be kept.

[default] com.rti.dds.infrastructure.HistoryQosPolicyKind.HistoryQosPolicyKind.KEEP_LAST_HISTORY_QOS

int depth

Specifies the number of samples to be kept, when the kind is com.rti.dds.infrastructure.HistoryQosPolicyKind.HistoryQosPolicyKind.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 <= com.rti.dds.infrastructure.ResourceLimitsQosPolicy.max_samples_per_instance

When the kind is com.rti.dds.infrastructure.HistoryQosPolicyKind.HistoryQosPolicyKind.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).

[default] 1

[range] [1,100 million], <= com.rti.dds.infrastructure.ResourceLimitsQosPolicy.max_samples_per_instance

RefilterQosPolicyKind refilter

<<eXtension>> Specifies how a writer should handle previously written samples to a new reader.

[default] com.rti.dds.infrastructure.RefilterQosPolicyKind.NONE_REFILTER_QOS