There are several types of statuses available for a DataWriter. You can use the get_*_status() operations (7.3.15 Setting DataWriter QosPolicies) to access them, or use a DataWriterListener (7.3.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.
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 7.6 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.
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 Table 7.7 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) |
This status includes internal protocol related metrics (such as the number of DDS samples pushed, pulled, filtered) and the status of wire-protocol traffic.
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 7.8 DDS_DataWriterProtocolStatus):
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.
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. |
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 of the first available DDS sample in the DataWriter's reliability queue. |
last_available_sample_ |
Sequence number of the last available DDS sample in the DataWriter's reliability queue. |
|
first_unacknowledged_sample_ |
Sequence number of the first unacknowledged DDS sample in the DataWriter's reliability queue. |
|
first_available_sample_virtual_ |
Virtual sequence number of the first available DDS sample in the DataWriter's reliability queue. |
|
last_available_sample_virtual_ |
Virtual sequence number of the last available DDS sample in the DataWriter's reliability queue. |
|
first_unacknowledged_sample_ |
Virtual sequence number of the first unacknowledged DDS sample in the DataWriter's reliability queue. |
|
DDS_SequenceNumber_t |
first_unacknowledged_sample_ |
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_ |
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. |
A change to this status indicates that the DataWriter failed to signal its liveliness within the time specified by the 7.5.15 LIVELINESS QosPolicy.
It is different than the 7.3.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 7.9 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.
A change to this status indicates that the DataWriter failed to write data within the time period set in its 7.5.7 DEADLINE QosPolicy.
The structure for this status appears in Table 7.10 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.
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 7.11 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_ |
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.
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 DDS Core Libraries Getting Started Guide Addendum for Extensible Types.) In addition, if user code has directed Connext DDS to ignore certain DataReaders, then those DataReaders will never be matched. See 18.4.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:
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 7.12 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 15.1 What is Discovery?.) 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_match_status() operation.
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:
For more about the reliable protocol used by Connext DDS and specifically, what it means for a DDS sample to be ‘unacknowledged,’ see 11. Reliable Communications.
The structure for this status appears in Table 7.13 DDS_ReliableWriterCacheChangedStatus.The supporting structure, DDS_ReliableWriterCacheEventCount, is described in Table 7.14 DDS_ReliableWriterCacheEventCount.
Type |
Field Name |
Description |
DDS_ReliableWriterCacheEventCount |
empty_reliable_writer_ |
How many times the reliable DataWriter's cache of unacknowledged DDS samples has become empty. |
full_reliable_writer_ |
How many times the reliable DataWriter's cache of unacknowledged DDS samples has become full. |
|
low_watermark_ |
How many times the reliable DataWriter's cache of unacknowledged DDS samples has fallen to the low watermark. |
|
high_watermark_ |
How many times the reliable DataWriter's cache of unacknowledged DDS samples has risen to the high watermark. |
|
DDS_Long |
unacknowledged_ |
The current number of unacknowledged DDS samples in the DataWriter's cache. |
unacknowledged_ |
The highest value that unacknowledged_sample_count has reached until now. |
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.
This status indicates that one or more reliable DataReaders has become active or inactive.
This status is the reciprocal status to the 8.3.7.4 LIVELINESS_CHANGED Status on the DataReader. It is different than 7.3.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 7.5.5 DATA_WRITER_PROTOCOL QosPolicy (DDS Extension).
This status is only used for DataWriters whose 7.5.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 7.15 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.
A change to this status indicates that ServiceRequest for the TopicQuery service is dispatched to this DataWriter for processing. For more information, see 24. Topic Queries.
The structure for this status appears in Table 7.16 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.
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 |
© 2020 RTI