Statuses for DataWriters

You are here: Part 2: Core Concepts > Sending Data > DataWriters > Statuses for DataWriters

Statuses for DataWriters

There are several types of statuses available for a DataWriter. You can use the get_*_status() operations (Setting DataWriter QosPolicies) to access them, or use a DataWriterListener (Setting Up DataWriterListeners) to listen for changes in their values. Each status has an associated data structure and is described in more detail in the following sections.

APPLICATION_ACKNOWLEDGMENT_STATUS
DATA_WRITER_CACHE_STATUS
DATA_WRITER_PROTOCOL_STATUS
LIVELINESS_LOST Status
OFFERED_DEADLINE_MISSED Status
OFFERED_INCOMPATIBLE_QOS Status
PUBLICATION_MATCHED Status
RELIABLE_WRITER_CACHE_CHANGED Status (DDS Extension)
RELIABLE_READER_ACTIVITY_CHANGED Status (DDS Extension)

APPLICATION_ACKNOWLEDGMENT_STATUS

This status indicates that a DataWriter has received an application-level acknowledgment for a DDS sample, and triggers a DataWriter callback:

void DDSDataWriterListener::on_application_acknowledgment( 
   DDSDataWriter * writer, 
   const DDS_AcknowledgmentInfo & info)

on_application_acknowledgment() is called when a DDS sample is application-level acknowledged. It provides identities of the DDS sample and the acknowledging DataReader, as well as user-specified response data sent from the DataReader by the acknowledgment message—see .

DDS_AcknowledgmentInfo
Type	Field Name	Description
DDS_InstanceHandle_t	subscription_handle	Subscription handle of the acknowledging DataReader.
struct DDS_SampleIdentity_t	sample_identity	Identity of the DDS sample being acknowledged.
DDS_Boolean	valid_response_data	Flag indicating validity of the user response data in the acknowledgment.
struct DDS_AckResponseData_t	response_data	User data payload of application-level acknowledgment message.

This status is only applicable when the DataWriter’s Reliability QosPolicy’s acknowledgment_kind is DDS_APPLICATION_AUTO_ACKNOWLEDGMENT_MODE or DDS_APPLICATION_EXPLICIT_ACKNOWLEDGMENT_MODE.

DATA_WRITER_CACHE_STATUS

This status keeps track of the number of DDS samples in the DataWriter’s queue.

This status does not have an associated Listener. You can access this status by calling the DataWriter’s get_datawriter_cache_status() operation, which will return the status structure described in .

DDS_DataWriterCacheStatus
Type	Field Name	Description
DDS_Long	sample_count_peak	Highest number of DDS samples in the DataWriter’s queue over the lifetime of the DataWriter.
DDS_Long	sample_count	Current number of DDS samples in the DataWriter’s queue (including DDS unregister and dispose samples)

DATA_WRITER_PROTOCOL_STATUS

This status includes internal protocol related metrics (such as the number of DDS samples pushed, pulled, filtered) and the status of wire-protocol traffic.

Pulled DDS samples are DDS samples sent for repairs (that is, DDS samples that had to be resent), for late joiners, and all DDS samples sent by the local DataWriter when push_on_write (in DATA_WRITER_PROTOCOL QosPolicy (DDS Extension)) is DDS_BOOLEAN_FALSE.
Pushed DDS samples are DDS samples sent on write() when push_on_write is DDS_BOOLEAN_TRUE.
Filtered DDS samples are DDS samples that are not sent due to DataWriter filtering (time-based filtering and ContentFilteredTopics).

This status does not have an associated Listener. You can access this status by calling the following operations on the DataWriter (all of which return the status structure described in ):

get_datawriter_protocol_status() returns the sum of the protocol status for all the matched subscriptions for the DataWriter.
get_matched_subscription_datawriter_protocol_status() returns the protocol status of a particular matched subscription, identified by a subscription_handle.
get_matched_subscription_datawriter_protocol_status_by_locator() returns the protocol status of a particular matched subscription, identified by a locator. (See Locator Format.)

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_DataWriterProtocolStatus
Type	Field Name	Description
DDS_LongLong	pushed_sample_count	The number of user DDS samples pushed on write from a local DataWriter to a matching remote DataReader.
	pushed_sample_count_change	The incremental change in the number of user DDS samples pushed on write from a local DataWriter to a matching remote DataReader since the last time the status was read.
	pushed_sample_bytes	The number of bytes of user DDS samples pushed on write from a local DataWriter to a matching remote DataReader.
	pushed_sample_bytes_change	The incremental change in the number of bytes of user DDS samples pushed on write from a local DataWriter to a matching remote DataReader since the last time the status was read.
DDS_LongLong	sent_heartbeat_count	The number of Heartbeats sent between a local DataWriter and matching remote DataReaders.
	sent_heartbeat_count_change	The incremental change in the number of Heartbeats sent between a local DataWriter and matching remote DataReaders since the last time the status was read.
	sent_heartbeat_bytes	The number of bytes of Heartbeats sent between a local DataWriter and matching remote DataReader.
	sent_heartbeat_bytes_change	The incremental change in the number of bytes of Heartbeats sent between a local DataWriter and matching remote DataReaders since the last time the status was read.
DDS_LongLong	pulled_sample_count	The number of user DDS samples pulled from local DataWriter by matching DataReaders.
	pulled_sample_count_change	The incremental change in the number of user DDS samples pulled from local DataWriter by matching DataReaders since the last time the status was read.
	pulled_sample_bytes	The number of bytes of user DDS samples pulled from local DataWriter by matching DataReaders.
	pulled_sample_bytes_change	The incremental change in the number of bytes of user DDS samples pulled from local DataWriter by matching DataReaders since the last time the status was read.
DDS_LongLong	received_ack_count	The number of ACKs from a remote DataReader received by a local DataWriter.
	received_ack_count_change	The incremental change in the number of ACKs from a remote DataReader received by a local DataWriter since the last time the status was read.
	received_ack_bytes	The number of bytes of ACKs from a remote DataReader received by a local DataWriter.
	received_ack_bytes_change	The incremental change in the number of bytes of ACKs from a remote DataReader received by a local DataWriter since the last time the status was read.
DDS_LongLong	received_nack_count	The number of NACKs from a remote DataReader received by a local DataWriter.
	received_nack_count_change	The incremental change in the number of NACKs from a remote DataReader received by a local DataWriter since the last time the status was read.
	received_nack_bytes	The number of bytes of NACKs from a remote DataReader received by a local DataWriter.
	received_nack_bytes_change	The incremental change in the number of bytes of NACKs from a remote DataReader received by a local DataWriter since the last time the status was read.
DDS_LongLong	sent_gap_count	The number of GAPs sent from local DataWriter to matching remote DataReaders.
	sent_gap_count_change	The incremental change in the number of GAPs sent from local DataWriter to matching remote DataReaders since the last time the status was read.
	sent_gap_bytes	The number of bytes of GAPs sent from local DataWriter to matching remote DataReaders.
	sent_gap_bytes_change	The incremental change in the number of bytes of GAPs sent from local DataWriter to matching remote DataReaders 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 send path.
DDS_LongLong	rejected_sample_count_change	The incremental change in the number of times a DDS sample is rejected due to exceptions in the send path since the last time the status was read.
DDS_Long	send_window_size	Current maximum number of outstanding DDS samples allowed in the DataWriter's queue.
DDS_SequenceNumber_t	first_available_sample_ sequence_number	Sequence number of the first available DDS sample in the DataWriter's reliability queue.
	last_available_sample_ sequence_number	Sequence number of the last available DDS sample in the DataWriter's reliability queue.
	first_unacknowledged_sample_ sequence_number	Sequence number of the first unacknowledged DDS sample in the DataWriter's reliability queue.
	first_available_sample_virtual_ sequence_number	Virtual sequence number of the first available DDS sample in the DataWriter's reliability queue.
	last_available_sample_virtual_ sequence_number	Virtual sequence number of the last available DDS sample in the DataWriter's reliability queue.
	first_unacknowledged_sample_ virtual_sequence_number	Virtual sequence number of the first unacknowledged DDS sample in the DataWriter's reliability queue.
DDS_SequenceNumber_t	first_unacknowledged_sample_ subscription_handle	Instance Handle of the matching remote DataReader for which the DataWriter has kept the first available DDS sample in the reliability queue.
DDS_SequenceNumber_t	first_unelapsed_keep_duration_ sample_sequence_number	Sequence number of the first DDS sample kept in the DataWriter's queue whose keep_duration (applied when disable_positive_acks is set) has not yet elapsed.

LIVELINESS_LOST Status

A change to this status indicates that the DataWriter failed to signal its liveliness within the time specified by the LIVELINESS QosPolicy.

It is different than the RELIABLE_READER_ACTIVITY_CHANGED Status (DDS Extension) status that provides information about the liveliness of a DataWriter’s matched DataReaders; this status reflects the DataWriter’s own liveliness.

The structure for this status appears in .

DDS_LivelinessLostStatus
Type	Field Name	Description
DDS_Long	total_count	Cumulative number of times the DataWriter failed to explicitly signal its liveliness within the liveliness period.
DDS_Long	total_count_change	The change in total_count since the last time the Listener was called or the status was read.

The DataWriterListener’s on_liveliness_lost() callback is invoked when this status changes. You can also retrieve the value by calling the DataWriter’s get_liveliness_lost_status() operation.

OFFERED_DEADLINE_MISSED Status

A change to this status indicates that the DataWriter failed to write data within the time period set in its DEADLINE QosPolicy.

The structure for this status appears in .

DDS_OfferedDeadlineMissedStatus
Type	Field Name	Description
DDS_Long	total_count	Cumulative number of times the DataWriter failed to write within its offered deadline.
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 DataWriter for which an offered deadline was missed.

The DataWriterListener’s on_offered_deadline_missed() operation is invoked when this status changes. You can also retrieve the value by calling the DataWriter’s get_deadline_missed_status() operation.

OFFERED_INCOMPATIBLE_QOS Status

A change to this status indicates that the DataWriter discovered a DataReader 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_OfferedIncompatibleQoSStatus
Type	Field Name	Description
DDS_Long	total_count	Cumulative number of times the DataWriter discovered a DataReader for the same Topic with a requested QoS that is incompatible with that offered by the DataWriter.
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 DataWriter discovered a DataReader for the same Topic with a requested QoS that is incompatible with that offered by the DataWriter.

The DataWriterListener’s on_offered_incompatible_qos() callback is invoked when this status changes. You can also retrieve the value by calling the DataWriter’s get_offered_incompatible_qos_status() operation.

PUBLICATION_MATCHED Status

A change to this status indicates that the DataWriter discovered a matching DataReader.

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 DataReaders, then those DataReaders will never be matched. See Ignoring Publications and Subscriptions for more on setting up a DomainParticipant to ignore specific DataReaders.

The structure for this status appears in .

DDS_PublicationMatchedStatus
Type	Field Name	Description
DDS_Long	total_count	Cumulative number of times the DataWriter discovered a "match" with a DataReader.
	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 DataReaders currently matched to the DataWriter.
	current_count_peak	The highest value that current_count has reached until now.
	current_count_change	The change in current_count since the last time the listener was called or the status was read.
DDS_InstanceHandle_t	last_subscription_handle	Handle to the last DataReader that matched the DataWriter causing the status to change.

The DataWriterListener’s on_publication_matched() callback is invoked when this status changes. You can also retrieve the value by calling the DataWriter’s get_publication_match_status() operation.

RELIABLE_WRITER_CACHE_CHANGED Status (DDS Extension)

A change to this status indicates that the number of unacknowledged DDS samples1If batching is enabled, this still refers to a number of DDS samples, not batches. in a reliable DataWriter's cache has reached one of these trigger points:

The cache is empty (contains no unacknowledged DDS samples)
The cache is full (the number of unacknowledged DDS samples has reached the value specified in DDS_ResourceLimitsQosPolicy::max_samples)
The number of unacknowledged DDS samples has reached a high or low watermark. See the high_watermark and low_watermark fields in of the DATA_WRITER_PROTOCOL QosPolicy (DDS Extension).

For more about the reliable protocol used by Connext DDS and specifically, what it means for a DDS sample to be ‘unacknowledged,’ see Reliable Communications.

The structure for this status appears in .The supporting structure, DDS_ReliableWriterCacheEventCount, is described in .

DDS_ReliableWriterCacheChangedStatus
Type	Field Name	Description
DDS_ReliableWriterCacheEventCount	empty_reliable_writer_ cache	How many times the reliable DataWriter's cache of unacknowledged DDS samples has become empty.
	full_reliable_writer_ cache	How many times the reliable DataWriter's cache of unacknowledged DDS samples has become full.
	low_watermark_ reliable_writer_cache	How many times the reliable DataWriter's cache of unacknowledged DDS samples has fallen to the low watermark.
	high_watermark_ reliable_writer_cache	How many times the reliable DataWriter's cache of unacknowledged DDS samples has risen to the high watermark.
DDS_Long	unacknowledged_ sample_count	The current number of unacknowledged DDS samples in the DataWriter's cache.
DDS_Long	unacknowledged_ sample_count_peak	The highest value that unacknowledged_sample_count has reached until now.

DDS_ReliableWriterCacheEventCount
Type	Field Name	Description
DDS_Long	total_count	The total number of times the event has occurred.
DDS_Long	total_count_change	The number of times the event has occurred since the Listener was last invoked or the status read.

The DataWriterListener’s on_reliable_writer_cache_changed() callback is invoked when this status changes. You can also retrieve the value by calling the DataWriter’s get_reliable_writer_cache_changed_status() operation.

If a reliable DataWriter's send window is finite, with both RtpsReliableWriterProtocol_t.min_send_window_size and RtpsReliableWriterProtocol_t.max_send_window_size set to positive values, then full_reliable_writer_cache_status counts the number of times the unacknowledged DDS sample count reaches the send window size.

RELIABLE_READER_ACTIVITY_CHANGED Status (DDS Extension)

This status indicates that one or more reliable DataReaders has become active or inactive.

This status is the reciprocal status to the LIVELINESS_CHANGED Status on the DataReader. It is different than LIVELINESS_LOST Status status on the DataWriter, in that the latter informs the DataWriter about its own liveliness; this status informs the DataWriter about the liveliness of its matched DataReaders.

A reliable DataReader is considered active by a reliable DataWriter with which it is matched if that DataReader acknowledges the DDS samples that it has been sent in a timely fashion. For the definition of "timely" in this context, see DATA_WRITER_PROTOCOL QosPolicy (DDS Extension).

This status is only used for DataWriters whose RELIABILITY QosPolicy is set to RELIABLE. For best-effort DataWriters, all counts in this status will remain at zero.

The structure for this status appears in .

DDS_ReliableReaderActivityChangedStatus
Type	Field Name	Description
DDS_Long	active_count	The current number of reliable readers currently matched with this reliable DataWriter.
	inactive_count	The number of reliable readers that have been dropped by this reliable DataWriter because they failed to send acknowledgments in a timely fashion.
	active_count_change	The change in the number of active reliable DataReaders since the Listener was last invoked or the status read.
	inactive_count_change	The change in the number of inactive reliable DataReaders since the Listener was last invoked or the status read.
DDS_InstanceHandle_t	last_instance_handle	The instance handle of the last reliable DataReader to be determined to be inactive.

The DataWriterListener’s on_reliable_reader_activity_changed() callback is invoked when this status changes. You can also retrieve the value by calling the DataWriter’s get_reliable_reader_activity_changed_status() operation.