RTI Connext Java API  Version 5.1.0
TimeBasedFilterQosPolicy Class Reference

Filter that allows a com.rti.dds.subscription.DataReader to specify that it is interested only in (potentially) a subset of the values of the data. More...

Inheritance diagram for TimeBasedFilterQosPolicy:
QosPolicy

Public Attributes

final Duration_t minimum_separation
 The minimum separation duration between subequent samples.
 
- 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

Filter that allows a com.rti.dds.subscription.DataReader to specify that it is interested only in (potentially) a subset of the values of the data.

The filter states that the com.rti.dds.subscription.DataReader does not want to receive more than one value each minimum_separation, regardless of how fast the changes occur.

Entity:
com.rti.dds.subscription.DataReader
Properties:
RxO = N/A
Changeable = YES

Usage

You can use this QoS policy to reduce the amount of data received by a com.rti.dds.subscription.DataReader. com.rti.dds.publication.DataWriter entities may send data faster than needed by a com.rti.dds.subscription.DataReader. For example, a com.rti.dds.subscription.DataReader of sensor data that is displayed to a human operator in a GUI application does not need to receive data updates faster than a user can reasonably perceive changes in data values. This is often measured in tenths (0.1) of a second up to several seconds. However, a com.rti.dds.publication.DataWriter of sensor information may have other com.rti.dds.subscription.DataReader entities that are processing the sensor information to control parts of the system and thus need new data updates in measures of hundredths (0.01) or thousandths (0.001) of a second.

With this QoS policy, different com.rti.dds.subscription.DataReader entities can set their own time-based filters, so that data published faster than the period set by a each com.rti.dds.subscription.DataReader will not be delivered to that com.rti.dds.subscription.DataReader.

The TIME_BASED_FILTER also applies to each instance separately; that is, the constraint is that the com.rti.dds.subscription.DataReader does not want to see more than one sample of each instance per minimum_separation period.

This QoS policy allows you to optimize resource usage (CPU and possibly network bandwidth) by only delivering the required amount of data to each com.rti.dds.subscription.DataReader, accommodating the fact that, for rapidly-changing data, different subscribers may have different requirements and constraints as to how frequently they need or can handle being notified of the most current values. As such, it can also be used to protect applications that are running on a heterogeneous network where some nodes are capable of generating data much faster than others can consume it.

For best effort data delivery, if the data type is unkeyed and the com.rti.dds.publication.DataWriter has an infinite com.rti.dds.infrastructure.LivelinessQosPolicy.lease_duration, RTI Connext will only send as many packets to a com.rti.dds.subscription.DataReader as required by the TIME_BASED_FILTER, no matter how fast com.rti.ndds.example.FooDataWriter.write is called.

For multicast data delivery to multiple DataReaders, the one with the lowest minimum_separation determines the DataWriter's send rate. For example, if a com.rti.dds.publication.DataWriter sends over multicast to two DataReaders, one with minimum_separation of 2 seconds and one with minimum_separation of 1 second, the DataWriter will send every 1 second.

In configurations where RTI Connext must send all the data published by the com.rti.dds.publication.DataWriter (for example, when the com.rti.dds.publication.DataWriter is reliable, when the data type is keyed, or when the com.rti.dds.publication.DataWriter has a finite com.rti.dds.infrastructure.LivelinessQosPolicy.lease_duration), only the data that passes the TIME_BASED_FILTER will be stored in the receive queue of the com.rti.dds.subscription.DataReader. Extra data will be accepted but dropped. Note that filtering is only applied on alive samples (that is, samples that have not been disposed/unregistered).

Consistency

It is inconsistent for a com.rti.dds.subscription.DataReader to have a minimum_separation longer than its DEADLINE period.

However, it is important to be aware of certain edge cases that can occur when your publication rate, minimum separation, and deadline period align and that can cause missed deadlines that you may not expect. For example, suppose that you nominally publish samples every second but that this rate can vary somewhat over time. You declare a minimum separation of 1 second to filter out rapid updates and set a deadline of two seconds so that you will be aware if the rate falls too low. Even if your update rate never wavers, you can still miss deadlines! Here's why:

Suppose you publish the first sample at time t=0 seconds. You then publish your next sample at t=1 seconds. Depending on how your operating system schedules the time-based filter execution relative to the publication, this second sample may be filtered. You then publish your third sample at t=2 seconds, and depending on how your OS schedules this publication in relation to the deadline check, you could miss the deadline.

This scenario demonstrates a couple of rules of thumb:

  • Beware of setting your minimum_separation to a value very close to your publication rate: you may filter more data than you intend to.
  • Beware of setting your minimum_separation to a value that is too close to your deadline period relative to your publication rate. You may miss deadlines.

See com.rti.dds.infrastructure.DeadlineQosPolicy for more information about the interactions between deadlines and time-based filters.

The setting of a TIME_BASED_FILTER – that is, the selection of a minimum_separation with a value greater than zero – is consistent with all settings of the HISTORY and RELIABILITY QoS. The TIME_BASED_FILTER specifies the samples that are of interest to the com.rti.dds.subscription.DataReader. The HISTORY and RELIABILITY QoS affect the behavior of the middleware with respect to the samples that have been determined to be of interest to the com.rti.dds.subscription.DataReader; that is, they apply after the TIME_BASED_FILTER has been applied.

In the case where the reliability QoS kind is com.rti.dds.infrastructure.ReliabilityQosPolicyKind.ReliabilityQosPolicyKind.RELIABLE_RELIABILITY_QOS, in steady-state – defined as the situation where the com.rti.dds.publication.DataWriter does not write new samples for a period "long" compared to the minimum_separation – the system should guarantee delivery of the last sample to the com.rti.dds.subscription.DataReader.

See Also
DeadlineQosPolicy
HistoryQosPolicy
ReliabilityQosPolicy

Member Data Documentation

final Duration_t minimum_separation

The minimum separation duration between subequent samples.

[default] 0 (meaning the com.rti.dds.subscription.DataReader is potentially interested in all values)

[range] [0,1 year], < com.rti.dds.infrastructure.DeadlineQosPolicy.period


RTI Connext Java API Version 5.1.0 Copyright © Mon Feb 3 2014 Real-Time Innovations, Inc