31.6 Statuses for DataWriters

There are several types of statuses available for a DataWriter. You can use the get_*_status() operations (31.15 Setting DataWriter QosPolicies) to access them, or use a DataWriterListener (31.4 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.

• 31.6.1 APPLICATION_ACKNOWLEDGMENT_STATUS
• 31.6.2 DATA_WRITER_CACHE_STATUS
• 31.6.3 DATA_WRITER_PROTOCOL_STATUS
• 31.6.4 LIVELINESS_LOST Status
• 31.6.5 OFFERED_DEADLINE_MISSED Status
• 31.6.6 OFFERED_INCOMPATIBLE_QOS Status
• 31.6.7 PUBLICATION_MATCHED Status
• 31.6.8 RELIABLE_WRITER_CACHE_CHANGED Status (DDS Extension)
• 31.6.9 RELIABLE_READER_ACTIVITY_CHANGED Status (DDS Extension)
• 31.6.10 SERVICE_REQUEST_ACCEPTED Status (DDS Extension)

31.6.1 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 Table 31.4 DDS_AcknowledgmentInfo.

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

31.6.2 DATA_WRITER_CACHE_STATUS

This status keeps track of the number of DDS samples and instances in the DataWriter’s queue. For information on instance states, see 19.1 Instance States.

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 Table 31.5 DDS_DataWriterCacheStatus.

Table 31.5 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. This number includes meta-samples, which represent the unregistration or disposal of an instance.
DDS_LongLong	alive_instance_count	Number of instances currently in the DataWriter's queue that have an instance_state of ALIVE.
DDS_LongLong	alive_instance_count_peak	Highest number of ALIVE instances in the DataWriter's queue over the lifetime of the DataWriter.
DDS_LongLong	disposed_instance_count	Number of instances currently in the DataWriter's queue that have an instance_state of NOT_ALIVE_DISPOSED.
DDS_LongLong	disposed_instance_count_peak	Highest number of NOT_ALIVE_DISPOSED instances in the DataWriter's queue over the lifetime of the DataWriter.
DDS_LongLong	unregistered_instance_count	Number of instances currently in the DataWriter's queue that the DataWriter has unregistered from via the unregister_instance operation.
DDS_LongLong	unregistered_instance_count_peak	Highest number of instances that the DataWriter has unregistered from, over the lifetime of the DataWriter.

31.6.3 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 47.5 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), but this field is not currently supported.
• DATA_FRAG messages are fragments of samples if you are using DDS-level fragmentation. See 34.3 Large Data Fragmentation for more information.

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 Table 31.6 DDS_DataWriterProtocolStatus):

• 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 24.1.1 Locator Format.)

Note: Status/data for a matched subscription is kept even if the DataReader is not active (has not responded to a heartbeat message with an ACK/NACK message after max_heartbeat_retries has been reached). The status/data will be removed only if the DataReader is gone: that is, the DataReader is destroyed and this change is propagated through a discovery update, or the DataReader's DomainParticipant is gone (either gracefully or its liveliness expired and Connext is configured to purge not-alive participants). Once a matched DataReader is gone, its status is deleted. If you try to get the status/data for a matched DataReader that is gone, the 'get status' or 'get data' call will return an error.

Table 31.6 DDS_DataWriterProtocolStatus

Type	Field Name	Description
DDS_LongLong	pushed_sample_count	The number of user DDS samples pushed on write from this DataWriter to a matching DataReader. This field counts protocol (RTPS) messages pushed by a DataWriter when writing, unregistering, and disposing. The count is the number of sends done internally, and it may be greater than the number of user writes. This field counts whole samples, not fragments (in the case of large data). The fragment count is tracked in the pushed_fragment_count.
	pushed_sample_count_change	Change in the pushed_sample_count since the last time the status was read.
	pushed_sample_bytes	The number of bytes of user DDS samples pushed on write from this DataWriter to a matching DataReader. This field counts bytes of protocol (RTPS) messages pushed by a DataWriter when writing, unregistering, and disposing. The count of bytes corresponds to the number of sends done internally, and it may be greater than the number of user writes. When data fragmentation is used (for large data), this statistic is incremented as fragments are written.
	pushed_sample_bytes_change	Change in pushed_sample_bytes since the last time the status was read.
DDS_LongLong	Not supported filtered_sample_count	The number of user samples preemptively filtered by this DataWriter due to ContentFilteredTopics.
	Not supported filtered_sample_count_change	Change in the filtered_sample_count since the last time the status was read.
	Not supported filtered_sample_bytes	The number of bytes of user samples preemptively filtered by this DataWriter due to ContentFilteredTopics.
	Not supported filtered_sample_bytes_change	Change in the filtered_sample_bytes since the last time the status was read.
DDS_LongLong	sent_heartbeat_count	The number of Heartbeats sent between this DataWriter and matching DataReaders.
	sent_heartbeat_count_change	Change in the sent_heartbeat_count since the last time the status was read.
	sent_heartbeat_bytes	The number of bytes of Heartbeats sent between this DataWriter and matching DataReaders.
	sent_heartbeat_bytes_change	The incremental change in the number of bytes of Heartbeats sent between this DataWriter and matching DataReaders since the last time the status was read.
DDS_LongLong	pulled_sample_count	The number of user DDS samples pulled from this DataWriter by matching DataReaders. When data fragmentation is used, this statistic is incremented as fragments are written.
	pulled_sample_count_change	Change in the pulled_sample_count since the last time the status was read.
	pulled_sample_bytes	The number of bytes of user DDS samples pulled from this DataWriter by matching DataReaders. When data fragmentation is used, this statistic is incremented as fragments are written.
	pulled_sample_bytes_change	Change in pulled_sample_bytes since the last time the status was read.
DDS_LongLong	received_ack_count	The number of ACKs from a DataReader received by this DataWriter.
	received_ack_count_change	Change in the received_ack_count since the last time the status was read.
	received_ack_bytes	The number of bytes of ACKs from a DataReader received by this DataWriter.
	received_ack_bytes_change	Change in received_ack_bytes since the last time the status was read.
DDS_LongLong	received_nack_count	The number of NACKs from a DataReader received by this DataWriter.
	received_nack_count_change	Change in the received_nack_count since the last time the status was read.
	received_nack_bytes	The number of bytes of NACKs from a DataReader received by this DataWriter.
	received_nack_bytes_change	Change in the received_nack_bytes since the last time the status was read.
DDS_LongLong	sent_gap_count	The number of GAPs sent from this DataWriter to matching DataReaders.
	sent_gap_count_change	Change in the sent_gap_count since the last time the status was read.
	sent_gap_bytes	The number of bytes of GAPs sent from this DataWriter to matching DataReaders.
	sent_gap_bytes_change	Change in the sent_gap_bytes since the last time the status was read.
DDS_LongLong	Not supported rejected_sample_count	These fields are not supported.
	Not supported rejected_sample_count_change
DDS_Long	send_window_size	Current size of the send window (maximum number of outstanding DDS samples allowed in the DataWriter's queue), as determined by the min/max_send_window_size fields in Table 47.14 DDS_RtpsReliableWriterProtocol_t. (See 47.5.4 Configuring the Send Window Size for information on how the send window size might change.)
DDS_LongLong	pushed_fragment_count	The number of fragments (DATA_FRAG messages) that have been pushed from this DataWriter to a DataReader. This count is incremented as each DATA_FRAG message is sent, not when the entire sample has been sent. Applicable only when data is fragmented.
	pushed_fragment_bytes	The number of bytes of DATA_FRAG messages that have been pushed by this DataWriter. This statistic is incremented as each DATA_FRAG message is sent, not when the entire sample has been sent. Applicable only when data is fragmented.
	pulled_fragment_count	The number of fragments (DATA_FRAG messages) that have been pulled from this DataWriter by a DataReader. This count is incremented as each DATA_FRAG message is sent, not when the entire sample has been sent. Applicable only when data is fragmented.
	pulled_fragment_bytes	The number of bytes of DATA_FRAG messages that have been pulled from this DataWriter by a DataReader. This statistic is incremented as each DATA_FRAG message is sent, not when the entire sample has been sent. Applicable only when data is fragmented.
DDS_LongLong	received_nack_fragment_count	The number of NACK_FRAG messages that have been received by this DataWriter. NACK FRAG RTPS messages are sent when large data is used in conjunction with reliable communication. They have the same properties as NACK messages, but instead of applying to samples, they apply to fragments. Applicable only when data is fragmented.
	received_nack_fragment_bytes	The number of bytes of NACK_FRAG messages that have been received by this DataWriter. NACK FRAG RTPS messages are sent when large data is used in conjunction with reliable communication. They have the same properties as NACK messages, but instead of applying to samples, they apply to fragments. Applicable only when data is fragmented.
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.
	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.

31.6.4 LIVELINESS_LOST Status

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

It is different than the 31.6.9 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 Table 31.7 DDS_LivelinessLostStatus.

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

31.6.5 OFFERED_DEADLINE_MISSED Status

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

The structure for this status appears in Table 31.8 DDS_OfferedDeadlineMissedStatus.

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

31.6.6 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 Table 31.9 DDS_OfferedIncompatibleQoSStatus.

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

31.6.7 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 or compatible data type, and compatible QosPolicies. (For more information on compatible data types, see the RTI Connext Core Libraries Extensible Types Guide.) In addition, if user code has directed Connext to ignore certain DataReaders, then those DataReaders will never be matched. See 27.2 Ignoring Publications and Subscriptions for more on setting up a DomainParticipant to ignore specific DataReaders.

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

• The matched DataReader's DomainParticipant has lost liveliness.
• This DataWriter or the matched DataReader has changed QoS such that the entities are now incompatible.
• The matched DataReader 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 31.10 DDS_PublicationMatchedStatus.

Table 31.10 DDS_PublicationMatchedStatus

Type	Field Name	Description
DDS_Long	total_count	Cumulative number of times that this DataWriter discovered a "match" with a DataReader. 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 DataWriter ever matched with a DataReader).
	current_count	The number of DataReaders currently matched to the DataWriter. 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_peak	Greatest number of DataReaders that matched this DataWriter simultaneously. That is, there was no moment in time when more than this many DataReaders matched this DataWriter. (As a result, total_count can be higher than current_count_peak.)
	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 DataReaders have become unmatched for one or more of the reasons listed above.
DDS_InstanceHandle_t	last_subscription_handle	This InstanceHandle can be used to look up which remote DataReader was the last to cause this DataWriter's status to change, using the DataWriter's get_matched_subscription_data() method. If the DataReader no longer matches this DataWriter due to any of the reasons listed above except incompatible QoS, then the DataReader has been purged from this DataWriter's DomainParticipant discovery database. (See Chapter 22 Discovery Overview.) In that case, the DataWriter's get_matched_subscription_data() method will not be able to return information about the DataReader. The only way to get information about the lost DataReader is if you cached the information previously.

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_matched_status() operation.

31.6.8 RELIABLE_WRITER_CACHE_CHANGED Status (DDS Extension)

A change to this status indicates that the number of unacknowledged DDS samples1 If 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 Table 47.14 DDS_RtpsReliableWriterProtocol_t of the 47.5 DATA_WRITER_PROTOCOL QosPolicy (DDS Extension).

For more about the reliable protocol used by Connext and specifically, what it means for a DDS sample to be ‘unacknowledged,’ see Chapter 32 Reliability Models for Sending Data.

The structure for this status appears in Table 31.11 DDS_ReliableWriterCacheChangedStatus.The supporting structure, DDS_ReliableWriterCacheEventCount, is described in Table 31.12 DDS_ReliableWriterCacheEventCount.

Table 31.11 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.
	unacknowledged_ sample_count_peak	The highest value that unacknowledged_sample_count has reached until now.
DDS_LongLong	replaced_unacknowledged_sample_count	Total number of unacknowledged samples that have been replaced by a DataWriter after applying the KEEP_LAST setting in the 47.12 HISTORY QosPolicy policy.

 

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

31.6.9 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 40.7.4 LIVELINESS_CHANGED Status on the DataReader. It is different than 31.6.4 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 47.5 DATA_WRITER_PROTOCOL QosPolicy (DDS Extension).

This status is only used for DataWriters whose 47.21 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 Table 31.13 DDS_ReliableReaderActivityChangedStatus.

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

31.6.10 SERVICE_REQUEST_ACCEPTED Status (DDS Extension)

A change to this status indicates that ServiceRequest for the TopicQuery service is dispatched to this DataWriter for processing. For more information, see Chapter 61 Topic Queries.

The structure for this status appears in Table 31.14 DDS_ServiceRequestAcceptedStatus.

The DataWriterListener’s on_service_request_accepted() callback is invoked when this status changes.

You can also retrieve the value by calling the DataWriter’s get_service_request_accepted_status() operation.

Table 31.14 DDS_ServiceRequestAcceptedStatus

Type	Field Name	Description
DDS_Long	total_count	The total cumulative number of ServiceRequests that have been accepted by a DataWriter.
	total_count_change	The incremental changes in total_count since the last time the listener was called or the status was read.
	current_count	The current number of ServiceRequests that have been accepted by this DataWriter.
	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_request_handle	A handle to the last DDS_ServiceRequest that caused the DataWriter's status to change.
DDS_Long	service_id	ID of the service to which the accepted Request belongs