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 4.3 Communication Statuses. 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).
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. |
|
DataWriter |
APPLICATION_ |
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. |
|
DATA_WRITER_CACHE |
The status of the DataWriter’s cache. This status does not have a Listener. |
||
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. |
||
DataWriter |
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. |
|
OFFERED_DEADLINE_ |
The deadline that the DataWriter has committed through its Deadline QosPolicy was not respected for a specific instance of the Topic. |
||
OFFERED_INCOMPATIBLE_ |
An offered QosPolicy value was incompatible with what was requested by a DataReader of the same Topic. |
||
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. |
||
RELIABLE_WRITER_ |
The number of unacknowledged DDS samples in a reliable DataWriter's cache has reached one of the predefined trigger points. |
7.3.6.8 RELIABLE_WRITER_CACHE_CHANGED Status (DDS Extension) |
|
RELIABLE_READER_ |
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. |
7.3.6.9 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. |
|
DataReader |
DATA_AVAILABLE |
New data (one or more DDS samples) are available for the specific DataReader. |
|
DATA_READER_CACHE |
The status of the reader's cache. This status does not have a Listener. |
||
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. |
||
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. |
||
DataReader |
REQUESTED_DEADLINE_ |
New data was not received for an instance of the Topic within the time period set by the DataReader’s Deadline QosPolicy. |
|
REQUESTED_ |
A requested QosPolicy value was incompatible with what was offered by a DataWriter of the same Topic. |
||
SAMPLE_LOST |
A DDS sample sent by Connext DDS has been lost (never received). |
||
SAMPLE_REJECTED |
A received DDS sample has been rejected due to a resource limit (buffers filled). |
||
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. |
Statuses can be grouped into two categories:
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.
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 4.3 Communication Statuses are read communications statuses: DATA_AVAILABLE and DATA_ON_READERS.
As mentioned in 4.1.4 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:
As seen in Figure 4.2: Status Changes for Plain Communication Status, 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 4.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 4.4.1 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.
As seen in Figure 4.3: Status Changes for Read Communication Status, 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:
Depending on the kind of StatusChangedFlag, the flag transitions to FALSE (that is, the status is reset) as follows:
Figure 4.3: Status Changes for Read Communication Status
© 2020 RTI