Statuses for DataReaders

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

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 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 Statuses for Subscribers and 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 (Setting Up SubscriberListeners) or DomainParticipantListener (Setting Up DomainParticipantListeners) has implemented an on_data_on_readers() callback. In that case, on_data_on_readers() will be invoked instead.

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 DDS_DataReaderCacheStatus; this operation will also reset the status so it is no longer considered “changed.”

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

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

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.

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.

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

The structure for this status appears in DDS_LivelinessChangedStatus.

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.

DDS_InstanceHandle_t

last_publication_handle

A handle to the last DataWriter to change its liveliness.

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

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 RELIABLE_READER_ACTIVITY_CHANGED Status (DDS Extension) for a DataWriter.

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 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 DDS Samples, Instances, and Keys.

The structure for this status appears in DDS_RequestedDeadlineMissedStatus.

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.

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

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

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

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

The structure for this status appears in DDS_SampleLostStatus.

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.

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

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

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

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

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

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

DDS_InstanceHandle_t

last_instance_handle

Handle to the data-instance for which the last DDS sample was rejected.

 

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.

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.

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.

DDS_REJECTED_BY_
SAMPLES_LIMIT

A resource limit on the total number of DDS samples was reached.

RESOURCE_LIMITS QosPolicy

DDS_REJECTED_BY_
SAMPLES_PER_
INSTANCE_LIMIT

A resource limit on the number of DDS samples per instance was reached.

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.

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

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 data type (implied by having the same Topic), and compatible QosPolicies. In addition, if user code has directed Connext DDS to ignore certain DataWriters, then those DataWriters will never be matched. See Ignoring Publications and Subscriptions for more on setting up a DomainParticipant to ignore specific DataWriters.

The structure for this status appears in DDS_SubscriptionMatchedStatus.

DDS_SubscriptionMatchedStatus

Type

Field Name

Description

DDS_Long

total_count

Cumulative number of times the DataReader discovered a "match" with a DataWriter.

total_count_change

The change in total_count since the last time the Listener was called or the status was read.

current_count

The number of DataWriters currently matched to the concerned DataReader.

current_count_change

The change in current_count since the last time the listener was called or the status was read.

current_count_peak

The highest value that current_count has reached until now.

DDS_InstanceHandle_t

last_publication_
handle

Handle to the last DataWriter that matched the DataReader causing the status to change.

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

© 2018 RTI