Statuses for DataReaders

You are here:

8.3.7 Statuses for DataReaders

There are several types of statuses available for a DataReader. You can use the get_*_status() operations (8.3.5 Checking DataReader Status and StatusConditions) to access and reset them, use a DataReaderListener (8.3.4 Setting Up DataReaderListeners) to listen for changes in their values (for those statuses that have Listeners), or use a StatusCondition and a WaitSet (4.6.8 StatusConditions) to wait for changes. Each status has an associated data structure and is described in more detail in the following sections.

8.3.7.1 DATA_AVAILABLE Status
8.3.7.2 DATA_READER_CACHE_STATUS
8.3.7.3 DATA_READER_PROTOCOL_STATUS
8.3.7.4 LIVELINESS_CHANGED Status
8.3.7.5 REQUESTED_DEADLINE_MISSED Status
8.3.7.6 REQUESTED_INCOMPATIBLE_QOS Status
8.3.7.7 SAMPLE_LOST Status
8.3.7.8 SAMPLE_REJECTED Status
8.3.7.9 SUBSCRIPTION_MATCHED Status

8.3.7.1 DATA_AVAILABLE Status

This status indicates that new data is available for the DataReader. In most cases, this means that one new DDS sample has been received. However, there are situations in which more than one DDS samples for the DataReader may be received before the DATA_AVAILABLE status changes. For example, if the DataReader has the 7.5.9 DURABILITY QosPolicy set to be non-VOLATILE, then the DataReader may receive a batch of old DDS data samples all at once. Or if data is being received reliably from DataWriters, Connext DDS may present several DDS samples of data simultaneously to the DataReader if they have been originally received out of order.

A change to this status also means that the DATA_ON_READERS status is changed for the DataReader’s Subscriber. This status is reset when you call read(), take(), or one of their variations.

Unlike most other statuses, this status (as well as DATA_ON_READERS for Subscribers) is a read communication status. See 8.2.9 Statuses for Subscribers and 4.3.1 Types of Communication Status for more information on read communication statuses.

The DataReaderListener’s on_data_available() callback is invoked when this status changes, unless the SubscriberListener (8.2.6 Setting Up SubscriberListeners) or DomainParticipantListener (9.3.6 Setting Up DomainParticipantListeners) has implemented an on_data_on_readers() callback. In that case, on_data_on_readers() will be invoked instead.

8.3.7.2 DATA_READER_CACHE_STATUS

This status keeps track of the number of DDS samples in the reader's cache.

This status does not have an associated Listener. You can access this status by calling the DataReader’s get_datareader_cache_status() operation, which will return the status structure described in Table 8.5 DDS_DataReaderCacheStatus; this operation will also reset the status so it is no longer considered “changed.”

Table 8.5 DDS_DataReaderCacheStatus
Type	Field Name	Description
DDS_Long	sample_count_peak	Highest number of DDS samples in the DataReader’s queue over the lifetime of the DataReader.
DDS_Long	sample_count	Current number of DDS samples in the DataReader’s queue. Includes DDS samples that may not yet be available to be read or taken by the user due to DDS samples being received out of order or settings in the 7.4.6 PRESENTATION QosPolicy.

8.3.7.3 DATA_READER_PROTOCOL_STATUS

The status of a DataReader’s internal protocol related metrics (such as the number of DDS samples received, filtered, rejected) and the status of wire protocol traffic. The structure for this status appears in Table 8.6 DDS_DataReaderProtocolStatus.

This status does not have an associated Listener. You can access this status by calling the following operations on the DataReader (which return the status structure described in Table 8.6 DDS_DataReaderProtocolStatus):

get_datareader_protocol_status() returns the sum of the protocol status for all the matched publications for the DataReader.

get_matched_publication_datareader_protocol_status() returns the protocol status of a particular matched publication, identified by a publication_handle.

The get_*_status() operations also reset the related status so it is no longer considered “changed.”

Note: Status for a remote entity is only kept while the entity is alive. Once a remote entity is no longer alive, its status is deleted. If you try to get the matched subscription status for a remote entity that is no longer alive, the ‘get status’ call will return an error.

Table 8.6 DDS_DataReaderProtocolStatus
Type	Field Name	Description
DDS_LongLong	received_sample_count	The number of samples received by a DataReader.
	received_sample_count_ change	The incremental change in the number of samples received from a DataReader since the last time the status was read.
	received_sample_bytes	The number of bytes received by a DataReader.
	received_sample_bytes_ change	The incremental change in the number of bytes received from a DataReader since the last time the status was read..
DDS_LongLong	duplicate_sample_count	The number of DDS samples from a remote DataWriter received, not for the first time, by a local DataReader.
	duplicate_sample_count_ change	The incremental change in the number of DDS samples from a remote DataWriter received, not for the first time, by a local DataReader since the last time the status was read.
	duplicate_sample_bytes	The number of bytes of DDS samples from a remote DataWriter received, not for the first time, by a local DataReader.
	duplicate_sample_bytes_ change	The incremental change in the number of bytes of DDS samples from a remote DataWriter received, not for the first time, by a local DataReader since the last time the status was read.
DDS_LongLong	filtered_sample_count	The number of DDS samples filtered by the local DataReader due to ContentFilteredTopics or Time-Based Filter.
	filtered_sample_count_ change	The incremental change in the number of DDS samples filtered by the local DataReader due to Content-FilteredTopics or Time-Based Filter since the last time the status was read.
	filtered_sample_bytes	The number of bytes of DDS samples filtered by the local DataReader due to ContentFilteredTopics or Time-Based Filter.
	filtered_sample_bytes_ change	The incremental change in the number of bytes of DDS samples filtered by the local DataReader due to ContentFilteredTopics or Time-Based Filter since the last time the status was read.
DDS_LongLong	received_heartbeat_count	The number of Heartbeats from a remote DataWriter received by a local DataReader.
	received_heartbeat_count_ change	The incremental change in the number of Heartbeats from a remote DataWriter received by a local DataReader since the last time the status was read.
	received_heartbeat_bytes	The number of bytes of Heartbeats from a remote DataWriter received by a local DataReader.
	received_heartbeat_bytes_ change	The incremental change in the number of bytes of Heartbeats from a remote DataWriter received by a local DataReader since the last time the status was read.
DDS_LongLong	sent_ack_count	The number of ACKs sent from a local DataReader to a matching remote DataWriter.
	sent_ack_count_change	The incremental change in the number of ACKs sent from a local DataReader to a matching remote DataWriter since the last time the status was read.
	sent_ack_bytes	The number of bytes of ACKs sent from a local DataReader to a matching remote DataWriter.
	sent_ack_bytes_change	The incremental change in the number of bytes of ACKs sent from a local DataReader to a matching remote DataWriter since the last time the status was read.
DDS_LongLong	sent_nack_count	The number of NACKs sent from a local DataReader to a matching remote DataWriter.
	sent_nack_count_change	The incremental change in the number of NACKs sent from a local DataReader to a matching remote DataWriter since the last time the status was read.
	sent_nack_bytes	The number of bytes of NACKs sent from a local DataReader to a matching remote DataWriter.
	sent_nack_bytes_change	The incremental change in the number of bytes of NACKs sent from a local DataReader to a matching remote DataWriter since the last time the status was read.
DDS_LongLong	received_gap_count	The number of GAPs received from remote DataWriter to this DataReader.
	received_gap_count_change	The incremental change in the number of GAPs received from remote DataWriter to this DataReader since the last time the status was read.
	received_gap_bytes	The number of bytes of GAPs received from remote DataWriter to this DataReader.
	received_gap_bytes_change	The incremental change in the number of bytes of GAPs received from remote DataWriter to this DataReader since the last time the status was read.
DDS_LongLong	rejected_sample_count	The number of times a DDS sample is rejected for unanticipated reasons in the receive path.
DDS_LongLong	rejected_sample_ count_change	The incremental change in the number of times a DDS sample is rejected for unanticipated reasons in the receive path since the last time the status was read.
DDS_ SequenceNumber_t	first_available_sample_ sequence_number	Sequence number of the first available DDS sample in a matched DataWriter's reliability queue. Applicable only when retrieving matched DataWriter statuses.
	last_available_sample_ sequence_number	Sequence number of the last available DDS sample in a matched DataWriter's reliability queue. Applicable only when retrieving matched DataWriter statuses.
	last_committed_sample_ sequence_number	Sequence number of the last committed DDS sample (i.e. available to be read or taken) in a matched DataWriter's reliability queue. Applicable only when retrieving matched DataWriter statuses. For best-effort DataReaders, this is the sequence number of the latest DDS sample received. For reliable DataReaders, this is the sequence number of the latest DDS sample that is available to be read or taken from the DataReader's queue.
DDS_Long	uncommitted_sample_count	Number of received DDS samples that are not yet available to be read or taken due to being received out of order. Applicable only when retrieving matched DataWriter statuses.

8.3.7.4 LIVELINESS_CHANGED Status

This status indicates that the liveliness of one or more matched DataWriters has changed (i.e., one or more DataWriters has become alive or not alive). The mechanics of determining liveliness between a DataWriter and a DataReader is specified in their 7.5.15 LIVELINESS QosPolicy.

The structure for this status appears in Table 8.7 DDS_LivelinessChangedStatus.

Table 8.7 DDS_LivelinessChangedStatus
Type	Field Name	Description
DDS_Long	alive_count	Number of matched DataWriters that are currently alive.
	not_alive_count	Number of matched DataWriters that are not currently alive.
	alive_count_change	The change in the alive_count since the last time the Listener was called or the status was read.
	not_alive_count_change	The change in the not_alive_count since the last time the Listener was called or the status was read. Note that a positive not_alive_count_change means one of the following: The DomainParticipant containing the matched DataWriter has lost liveliness or has been deleted. The matched DataWriter has lost liveliness or has been deleted.
DDS_InstanceHandle_t	last_publication_handle	This InstanceHandle can be used to look up which remote DataWriter was the last to cause this DataReader's status to change, using the DataReader's get_matched_publication_data() method. It's possible that the DataWriter has been purged from the discovery database. If so, get_matched_publication_data() will not be able to return information about the DataWriter. In this case, the only way to get information about the lost DataWriter is if you cached the information previously.

The DataReaderListener’s on_liveliness_changed() callback may be called for the following reasons:

The liveliness of any DataWriter matching this DataReader (as defined by the 7.5.15 LIVELINESS QosPolicy) is lost.
A DataWriter's liveliness is recovered after being lost.
A new matching DataWriter has been discovered.
A QoS Policy has changed such that a DataWriter that matched this DataReader before no longer matches (such as a change to the PartitionQosPolicy). In this case, Connext DDS will no longer keep track of the DataWriter's liveliness. Furthermore:
- If the DataWriter was alive when it and the DataReader stopped matching: alive_count will decrease (since there’s one less matching alive DataWriter) and not_alive_count will remain the same (since the DataWriter is still alive).
- If the DataWriter was not alive when it and the DataReader stopped matching: alive_count will remain the same (since the matching DataWriter was not alive) and not_alive_count will decrease (since there’s one less not-alive matching DataWriter).
A QoS Policy (such as the PartitionQosPolicy) has changed such that a DataWriter that was unmatched with the DataReader now matches.

You can also retrieve the value by calling the DataReader’s get_liveliness_changed_status() operation; this will also reset the status so it is no longer considered “changed.”

This status is reciprocal to the 7.3.6.9 RELIABLE_READER_ACTIVITY_CHANGED Status (DDS Extension) for a DataWriter.

8.3.7.5 REQUESTED_DEADLINE_MISSED Status

This status indicates that the DataReader did not receive a new DDS sample for an data-instance within the time period set in the DataReader’s 7.5.7 DEADLINE QosPolicy. For non-keyed Topics, this simply means that the DataReader did not receive data within the DEADLINE period. For keyed Topics, this means that for one of the data-instances that the DataReader was receiving, it has not received a new DDS sample within the DEADLINE period. For more information about keys and instances, see 2.4 DDS Samples, Instances, and Keys.

The structure for this status appears in Table 8.8 DDS_RequestedDeadlineMissedStatus.

Table 8.8 DDS_RequestedDeadlineMissedStatus
Type	Field Name	Description
DDS_Long	total_count	Cumulative number of times that the deadline was violated for any instance read by the DataReader.
DDS_Long	total_count_change	The change in total_count since the last time the Listener was called or the status was read.
DDS_InstanceHandle_t	last_instance_handle	Handle to the last data-instance in the DataReader for which a requested deadline was missed.

The DataReaderListener’s on_requested_deadline_missed() callback is invoked when this status changes. You can also retrieve the value by calling the DataReader’s get_requested_deadline_missed_status() operation; this will also reset the status so it is no longer considered “changed.”

8.3.7.6 REQUESTED_INCOMPATIBLE_QOS Status

A change to this status indicates that the DataReader discovered a DataWriter for the same Topic, but that DataReader had requested QoS settings incompatible with this DataWriter’s offered QoS.

The structure for this status appears in Table 8.9 DDS_RequestedIncompatibleQosStatus .

Table 8.9 DDS_RequestedIncompatibleQosStatus
Type	Field Name	Description
DDS_Long	total_count	Cumulative number of times the DataReader discovered a DataWriter for the same Topic with an offered QoS that is incompatible with that requested by the DataReader.
DDS_Long	total_count_change	The change in total_count since the last time the Listener was called or the status was read.
DDS_QosPolicyId_t	last_policy_id	The ID of the QosPolicy that was found to be incompatible the last time an incompatibility was detected. (Note: if there are multiple incompatible policies, only one of them is reported here.)
DDS_QosPolicyCountSeq	policies	A list containing—for each policy—the total number of times that the DataReader discovered a DataWriter for the same Topic with a offered QoS that is incompatible with that requested by the DataReader.

The DataReaderListener’s on_requested_incompatible_qos() callback is invoked when this status changes. You can also retrieve the value by calling the DataReader’s get_requested_incompatible_qos_status() operation; this will also reset the status so it is no longer considered “changed.”

8.3.7.7 SAMPLE_LOST Status

This status indicates that one or more DDS samples written by a matched DataWriter have failed to be received.

For a DataReader, when there are insufficient resources to accept incoming DDS samples of data, DDS samples may be dropped by the receiving application. Those DDS samples are considered to be REJECTED (see 8.3.7.8 SAMPLE_REJECTED Status). But DataWriters are limited in the number of published DDS data samples that they can store, so that if a DataWriter continues to publish DDS data samples, new data may overwrite old data that have not yet been received by the DataReader. The DDS samples that are overwritten can never be resent to the DataReader and thus are considered to be lost.

This status applies to reliable and best-effort DataReaders, see the 7.5.21 RELIABILITY QosPolicy.

The structure for this status appears in Table 8.10 DDS_SampleLostStatus.

Table 8.10 DDS_SampleLostStatus
Type	Field Name	Description
DDS_Long	total_count	Cumulative count of all the DDS samples that have been lost, across all instances of data written for the Topic.
DDS_Long	total_count_change	The incremental number of DDS samples lost since the last time the Listener was called or the status was read.
DDS_SampleLostStatusKind	last_reason	The reason the last DDS sample was lost. See Table 8.11 DDS_SampleLostStatusKind.

The reason the DDS sample was lost appears in the last_reason field. The possible values are listed in Table 8.11 DDS_SampleLostStatusKind.

Table 8.11 DDS_SampleLostStatusKind
Reason Kind	Description
NOT_LOST	The DDS sample was not lost.
LOST_BY_AVAILABILITY_WAITING_TIME	AvailabilityQosPolicy’s max_data_availability_waiting_time expired.
LOST_BY_INCOMPLETE_COHERENT_SET	A DDS sample is lost because it is part of an incomplete coherent set.
LOST_BY_INSTANCES_LIMIT	A resource limit on the number of instances was reached.
LOST_BY_LARGE_COHERENT_SET	A DDS sample is lost because it is part of a large coherent set.
LOST_BY_REMOTE_WRITER_SAMPLES_ PER_VIRTUAL_QUEUE_LIMIT"	A resource limit on the number of DDS samples published by a remote writer on behalf of a virtual writer that a DataReader may store was reached.
LOST_BY_REMOTE_WRITERS_PER_ INSTANCE_LIMIT	A resource limit on the number of remote writers for a single instance from which a DataReader may read was reached.
LOST_BY_REMOTE_WRITERS_PER_ SAMPLE_LIMIT	A resource limit on the number of remote writers per DDS sample was reached.
LOST_BY_SAMPLES_PER_REMOTE_ WRITER_LIMIT	A resource limit on the number of DDS samples from a given remote writer that a DataReader may store was reached.
LOST_BY_VIRTUAL_WRITERS_LIMIT	A resource limit on the number of virtual writers from which a DataReader may read was reached.
LOST_BY_WRITER	A DataWriter removed the DDS sample before being received by the DataReader.

The DataReaderListener’s on_sample_lost() callback is invoked when this status changes. You can also retrieve the value by calling the DataReader’s get_sample_lost_status() operation; this will also reset the status so it is no longer considered “changed.”

8.3.7.8 SAMPLE_REJECTED Status

This status indicates that one or more DDS samples received from a matched DataWriter have been dropped by the DataReader because a resource limit would have been exceeded. For example, if the receive queue is full, the number of DDS samples in the queue is equal to the max_samples parameter of the 7.5.22 RESOURCE_LIMITS QosPolicy.

The structure for this status appears in Table 8.12 DDS_SampleRejectedStatus. The reason the DDS sample was rejected appears in the last_reason field. The possible values are listed in Table 8.13 DDS_SampleRejectedStatusKind.

Table 8.12 DDS_SampleRejectedStatus
Type	Field Name	Description
DDS_Long	total_count	Cumulative count of all the DDS samples that have been rejected by the DataReader.
	total_count_change	The incremental number of DDS samples rejected since the last time the Listener was called or the status was read.
	current_count	The current number of writers with which the DataReader is matched.
	current_count_change	The change in current_count since the last time the Listener was called or the status was read.
DDS_SampleRejectedStatusKind	last_reason	Reason for rejecting the last DDS sample. See Table 8.13 DDS_SampleRejectedStatusKind.
DDS_InstanceHandle_t	last_instance_handle	Handle to the data-instance for which the last DDS sample was rejected.

Table 8.13 DDS_SampleRejectedStatusKind
Reason Kind	Description	Related QosPolicy
DDS_NOT_REJECTED	DDS sample was accepted.
DDS_REJECTED_BY_ INSTANCES_LIMIT	A resource limit on the number of instances that can be handled at the same time by the DataReader was reached.	7.5.22 RESOURCE_LIMITS QosPolicy
DDS_REJECTED_BY_ REMOTE_WRITERS_LIMIT	A resource limit on the number of DataWriters from which a DataReader may read was reached.	8.6.2 DATA_READER_RESOURCE_LIMITS QosPolicy (DDS Extension)
DDS_REJECTED_BY_ REMOTE_WRITERS_PER_INSTANCE_LIMIT	A resource limit on the number of DataWriters for a single instance from which a DataReader may read was reached.	8.6.2 DATA_READER_RESOURCE_LIMITS QosPolicy (DDS Extension)
DDS_REJECTED_BY_ SAMPLES_LIMIT	A resource limit on the total number of DDS samples was reached.	7.5.22 RESOURCE_LIMITS QosPolicy
DDS_REJECTED_BY_ SAMPLES_PER_INSTANCE_LIMIT	A resource limit on the number of DDS samples per instance was reached.	7.5.22 RESOURCE_LIMITS QosPolicy
DDS_REJECTED_BY_ SAMPLES_PER_REMOTE_WRITER_LIMIT	A resource limit on the number of DDS samples that a DataReader may store from a specific DataWriter was reached.	8.6.2 DATA_READER_RESOURCE_LIMITS QosPolicy (DDS Extension)
DDS_REJECTED_BY_ VIRTUAL_WRITERS_LIMIT	A resource limit on the number of virtual writers from which a DataReader may read was reached.
DDS_REJECTED_BY_ REMOTE_WRITERS_PER_SAMPLE_LIMIT	A resource limit on the number of remote writers per DDS sample was reached.
DDS_REJECTED_BY_ REMOTE_WRITER_SAMPLES_PER_VIRTUAL_QUEUE_LIMIT	A resource limit on the number of DDS samples published by a remote writer on behalf of a virtual writer that a DataReader may store was reached.

The DataReaderListener’s on_sample_rejected() callback is invoked when this status changes. You can also retrieve the value by calling the DataReader’s get_sample_rejected_status() operation; this will also reset the status so it is no longer considered “changed.”

8.3.7.9 SUBSCRIPTION_MATCHED Status

A change to this status indicates that the DataReader discovered a matching DataWriter. A ‘match’ occurs only if the DataReader and DataWriter have the same Topic, same or compatible data type, and compatible QosPolicies. (For more information on compatible data types, see the RTI Connext DDS Core Libraries Getting Started Guide Addendum for Extensible Types.) In addition, if user code has directed Connext DDS to ignore certain DataWriters, then those DataWriters will never be matched. See 18.4.2 Ignoring Publications and Subscriptions for more on setting up a DomainParticipant to ignore specific DataWriters.

This status is also changed (and the listener, if any, called) when a match is ended. A DataReader will become unmatched from a DataWriter when that DataWriter goes away for any of the following reasons:

The DomainParticipant containing the matched DataWriter has lost liveliness.
The DataReader or the matched DataWriter has changed QoS such that the entities are now incompatible.
The matched DataWriter has been deleted.

This status may reflect changes from multiple match or unmatch events, and the current_count_change can be used to determine the number of changes since the listener was called back or the status was checked.

The structure for this status appears in Table 8.14 DDS_SubscriptionMatchedStatus.

Table 8.14 DDS_SubscriptionMatchedStatus
Type	Field Name	Description
DDS_Long	total_count	Cumulative number of times the DataReader discovered a "match" with a DataWriter. This number increases whenever a new match is discovered. It does not decrease when an existing match goes away for any of the reasons listed above.
	total_count_change	The changes in total_count since the last time the listener was called or the status was read. Note that this number will never be negative (because it’s the total number of times the DataReader ever matched with a DataWriter).
	current_count	The number of DataWriters currently matched to the concerned DataReader. This number increases when a new match is discovered and decreases when an existing match goes away for any of the reasons listed above.
	current_count_change	The change in current_count since the last time the listener was called or the status was read. Note that a negative current_count_change means that one or more DataWriters have become unmatched for one or more of the reasons listed above.
	current_count_peak	Greatest number of DataWriters that matched this DataReader simultaneously. That is, there was no moment in time when more than this many DataWriters matched this DataReader. (As a result, total_count can be higher than current_count_peak.)
DDS_InstanceHandle_t	last_publication_ handle	This InstanceHandle can be used to look up which remote DataWriter was the last to cause this DataReader's status to change, using the DataReader's get_matched_publication_data() method. If the DataWriter no longer matches this DataReader due to any of the reasons listed above except incompatible QoS, then the DataWriter has been purged from this DataReader's DomainParticipant discovery database. (See 15.1 What is Discovery?.) In that case, the DataReader's get_matched_publication_data method will not be able to return information about the DataWriter. The only way to get information about the lost DataWriter is if you cached the information previously.

The DataReaderListener’s on_subscription_matched() callback is invoked when this status changes. You can also retrieve the value by calling the DataReader’s get_subscription_match_status() operation; this will also reset the status so it is no longer considered “changed.”