Types of Communication Status

Each Entity is associated with a set of Status objects representing the “communication status” of that Entity. The list of statuses actively monitored by Connext DDS is provided in Table 3 . A status structure contains values that give you more information about the status; for example, how many times the event has occurred since the last time the user checked the status, or how many time the event has occurred in total.

Changes to status values cause activation of corresponding StatusCondition objects and trigger invocation of the corresponding Listener functions to asynchronously inform the application that the status has changed. For example, a change in a Topic’s INCONSISTENT_TOPIC_STATUS may trigger the TopicListener’s on_inconsistent_topic() callback routine (if such a Listener is installed).

Table 3 Communication Statuses

Related Entity	Status (DDS_*_STATUS)	Description	Reference
Topic	INCONSISTENT_TOPIC	Another Topic exists with the same name but different characteristics—for example, a different type.	INCONSISTENT_TOPIC Status
Data-Writer	APPLICATION_ ACKNOWLEDGMENT	This status indicates that a DataWriter has received an application-level acknowledgment for a DDS sample. The listener provides the identities of the DDS sample and acknowledging DataReader, as well as user-specified response data sent from the DataReader by the acknowledgment message.	Application Acknowledgment
	DATA_WRITER_CACHE	The status of the DataWriter’s cache. This status does not have a Listener.	DATA_WRITER_CACHE_STATUS
	DATA_WRITER_PROTOCOL	The status of a DataWriter’s 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 a Listener.	DATA_WRITER_PROTOCOL_STATUS
	LIVELINESS_LOST	The liveliness that the DataWriter has committed to (through its Liveliness QosPolicy) was not respected (assert_liveliness() or write() not called in time), thus DataReaders may consider the DataWriter as no longer active.	LIVELINESS_LOST Status
	OFFERED_DEADLINE_ MISSED	The deadline that the DataWriter has committed through its Deadline QosPolicy was not respected for a specific instance of the Topic.	OFFERED_DEADLINE_MISSED Status
	OFFERED_INCOMPATIBLE_ QOS	An offered QosPolicy value was incompatible with what was requested by a DataReader of the same Topic.	OFFERED_INCOMPATIBLE_QOS Status
	PUBLICATION_MATCHED	The DataWriter found a DataReader that matches the Topic, has compatible QoSs and a common partition, or a previously matched DataReader has been deleted.	PUBLICATION_MATCHED Status
	RELIABLE_WRITER_ CACHE_CHANGED	The number of unacknowledged DDS samples in a reliable DataWriter's cache has reached one of the predefined trigger points.	RELIABLE_WRITER_CACHE_CHANGED Status (DDS Extension)
	RELIABLE_READER_ ACTIVITY_CHANGED	One or more reliable DataReaders has either been discovered, deleted, or changed between active and inactive state as specified by the LivelinessQosPolicy of the DataReader.	RELIABLE_READER_ACTIVITY_CHANGED Status (DDS Extension)
Subscriber	DATA_ON_READERS	New data is available for any of the readers that were created from the Subscriber.	Statuses for Subscribers
Data-Reader	DATA_AVAILABLE	New data (one or more DDS samples) are available for the specific DataReader.	DATA_AVAILABLE Status
	DATA_READER_CACHE	The status of the reader's cache. This status does not have a Listener.	DATA_READER_CACHE_STATUS
	DATA_READER_PROTOCOL	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. This status does not have a Listener.	DATA_READER_PROTOCOL_STATUS
	LIVELINESS_CHANGED	The liveliness of one or more DataWriters that were writing instances read by the DataReader has either been discovered, deleted, or changed between active and inactive state as specified by the LivelinessQosPolicy of the DataWriter.	LIVELINESS_CHANGED Status
	REQUESTED_DEADLINE_ MISSED	New data was not received for an instance of the Topic within the time period set by the DataReader’s Deadline QosPolicy.	REQUESTED_DEADLINE_MISSED Status
	REQUESTED_ INCOMPATIBLE_QOS	A requested QosPolicy value was incompatible with what was offered by a DataWriter of the same Topic.	REQUESTED_INCOMPATIBLE_QOS Status
	SAMPLE_LOST	A DDS sample sent by Connext DDS has been lost (never received).	SAMPLE_LOST Status
	SAMPLE_REJECTED	A received DDS sample has been rejected due to a resource limit (buffers filled).	SAMPLE_REJECTED Status
	SUBSCRIPTION_MATCHED	The DataReader has found a DataWriter that matches the Topic, has compatible QoSs and a common partition, or an existing matched DataWriter has been deleted.	SUBSCRIPTION_MATCHED Status

Statuses can be grouped into two categories:

• Plain communication status:

In addition to a flag that indicates whether or not a status has changed, a plain communication status also contains state and thus has a corresponding structure to hold its current value.

• Read communication status:

A read communication status is more like an event and has no state other than whether or not it has occurred. Only two statuses listed in Table 3 are read communications statuses: DATA_AVAILABLE and DATA_ON_READERS.

As mentioned in Getting Status and Status Changes, all Entities have a get_status_changes() operation that can be used to explicitly poll for changes in any status related to the entity. For plain statuses, each entry has operations to get the current value of the status; for example, the Topic class has a get_inconsistent_topic_status() operation. For read statuses, your application should use the take() operation on the DataReader to retrieve the newly arrived data that is indicated by DATA_AVAILABLE and DATA_ON_READER.

Note that the two read communication statuses do not change independently. If data arrives for a DataReader, then its DATA_AVAILABLE status changes. At the same time, the DATA_ON_READERS status changes for the DataReader’s Subscriber.

Both types of status have a StatusChangedFlag. This flag indicates whether that particular communication status has changed since the last time the status was read by the application. The way the StatusChangedFlag is maintained is slightly different for the plain communication status and the read communication status, as described in the following sections:

• Changes in Plain Communication Status
• Changes in Read Communication Status

Changes in Plain Communication Status

As seen in Figure 2, for the plain communication status, the StatusChangedFlag flag is initially set to FALSE. It becomes TRUE whenever the plain communication status changes and is reset to FALSE each time the application accesses the plain communication status via the proper get_*_status() operation.

Figure 2 Status Changes for Plain Communication Status

The communication status is also reset to FALSE whenever the associated listener operation is called, as the listener implicitly accesses the status which is passed as a parameter to the operation.

The fact that the status is reset prior to calling the listener means that if the application calls the get_*_status() operation from inside the listener, it will see the status already reset.

An exception to this rule is when the associated listener is the 'nil' listener. The 'nil' listener is treated as a NO-OP and the act of calling the 'nil' listener does not reset the communication status. (See Types of Listeners.)

For example, the value of the StatusChangedFlag associated with the REQUESTED_DEADLINE_MISSED status will become TRUE each time new deadline occurs (which increases the RequestedDeadlineMissed status’ total_count field). The value changes to FALSE when the application accesses the status via the corresponding get_requested_deadline_missed_status() operation on the proper Entity.

Changes in Read Communication Status

As seen in Figure 3, for the read communication status, the StatusChangedFlag flag is initially set to FALSE. The StatusChangedFlag becomes TRUE when either a DDS data sample arrives or the ViewStateKind, SampleStateKind, or InstanceStateKind of any existing DDS sample changes for any reason other than a call to one of the read/take operations. Specifically, any of the following events will cause the StatusChangedFlag to become TRUE:

• The arrival of new data.
• A change in the InstanceStateKind of a contained instance. This can be caused by either:
  • Notification that an instance has been disposed by:
    • the DataWriter that owns it, if OWNERSHIP = EXCLUSIVE
    • or by any DataWriter, if OWNERSHIP = SHARED
  • The loss of liveliness of the DataWriter of an instance for which there is no other DataWriter.
  • The arrival of the notification that an instance has been unregistered by the only DataWriter that is known to be writing the instance.

Depending on the kind of StatusChangedFlag, the flag transitions to FALSE (that is, the status is reset) as follows:

• The DATA_AVAILABLE StatusChangedFlag becomes FALSE when either on_data_available() is called or the read/take operation (or their variants) is called on the associated DataReader.
• The DATA_ON_READERS StatusChangedFlag becomes FALSE when any of the following occurs:
  • on_data_on_readers() is called.
  • on_data_available() is called on any DataReader belonging to the Subscriber.
  • read(), take(), or one of their variants is called on any DataReader belonging to the Subscriber.

Figure 3 Status Changes for Read Communication Status

© 2015 RTI