3.1.3. Status¶

Each Entity is associated with a set of Status objects whose values represent the communication status of that Entity. Changes on the status values occur due to communication events related to each of the entities, e.g., when new data arrives, a new participant is discovered, or a remote endpoint is lost. The status is decomposed into several status objects, each concerning a different aspect of the communication, so that each of these status objects can vary independently of the others.

Changes on a status object trigger the corresponding Listener callbacks that allow the Entity to inform the application about the event. For a given status object with name fooStatus, the entity listener interface defines a callback function on_foo() that will be called when the status changes. Beware that some statuses have data members that are reset every time the corresponding listener is called. The only exception to this rule is when the entity has no listener attached, so the callback cannot be called. See the documentation of each status for details.

Conditions and Wait-sets provide the application with an alternative mechanism to make it aware of changes on status objects, by means of a StatusCondition. The advantage of this mechanism is that the application can wait for changes on several entities at the same time. It will also help the determinism of your system, as the notification is not processed on an internal thread, as it is done when using listeners.

The entities expose functions to access the value of its statuses. For a given status with name fooStatus, the entity exposes a member function get_foo() to access the data in its fooStatus. The only exceptions are DataOnReaders and DataAvailable. These getter functions return a read-only struct where all data members are public and accessible to the application. Beware that some statuses have data members that are reset every time the getter function is called by the application. See the documentation of each status for details.

The following subsections describe each of the status objects, their data members, and to which Entity type they concern. The next table offers a quick reference as well as the corresponding bit for each status in the StatusMask.

Status Name	Entity	Listener callback	Accessor	Bit
InconsistentTopicStatus	Topic	`on_inconsistent_topic()`	`get_inconsistent_topic_status()`	0
OfferedDeadlineMissedStatus	DataWriter	`on_offered_deadline_missed()`	`get_offered_deadline_missed_status()`	1
RequestedDeadlineMissedStatus	DataReader	`on_requested_deadline_missed()`	`get_requested_deadline_missed_status()`	2
OfferedIncompatibleQosStatus	DataWriter	`on_offered_incompatible_qos()`	`get_offered_incompatible_qos_status()`	5
RequestedIncompatibleQosStatus	DataReader	`on_requested_incompatible_qos()`	`get_requested_incompatible_qos_status()`	6
SampleLostStatus	DataReader	`on_sample_lost()`	`get_sample_lost_status()`	7
SampleRejectedStatus	DataReader	`on_sample_rejected()`	`get_sample_rejected_status()`	8
DataOnReaders	Subscriber	`on_data_on_readers()`	N/A	9
DataAvailable	DataReader	`on_data_available()`	N/A	10
LivelinessLostStatus	DataWriter	`on_liveliness_lost()`	`get_liveliness_lost_status()`	11
LivelinessChangedStatus	DataReader	`on_liveliness_changed()`	`get_liveliness_changed_status()`	12
PublicationMatchedStatus	DataWriter	`on_publication_matched()`	`get_publication_matched_status()`	13
SubscriptionMatchedStatus	DataReader	`on_subscription_matched()`	`get_subscription_matched_status()`	14

3.1.3.1. InconsistentTopicStatus¶

This status changes every time an inconsistent remote Topic is discovered, that is, one with the same name but different characteristics than the current Topic. See InconsistentTopicStatus.

List of status data members:

Data Member Name	Type
`total_count`	`int32_t`
`total_count_change`	`int32_t`

total_count: Total cumulative count of inconsistent Topics discovered since the creation of the current Topic.
total_count_change: The change in total_count since the last time on_inconsistent_topic() was called or the status was read.

Warning

Currently this status is not supported and will be implemented in future releases. As a result, trying to access this status will return NOT_SUPPORTED and the corresponding listener will never be called.

3.1.3.2. DataOnReaders¶

This status becomes active every time there is new data available for the application on any DataReader belonging to the current Subscriber. There is no getter function to access this status, as it does not keep track of any information related to the data itself. Its only purpose is to trigger the on_data_on_readers() callback on the listener attached to the DataReader.

3.1.3.3. DataAvailable¶

This status becomes active every time there is new data available for the application on the DataReader. There is no getter function to access this status, as it does not keep track of any information related to the data itself. Its only purpose is to trigger the on_data_available() callback on the listener attached to the DataReader.

3.1.3.4. LivelinessChangedStatus¶

This status changes every time the liveliness status of a matched DataWriter has changed. Either because a DataWriter that was inactive has become active or the other way around. See LivelinessChangedStatus.

List of status data members:

Data Member Name	Type
`alive_count`	`int32_t`
`not_alive_count`	`int32_t`
`alive_count_change`	`int32_t`
`not_alive_count_change`	`int32_t`
`last_publication_handle`	`InstanceHandle_t`

alive_count: Total number of currently active DataWriters. This count increases every time a newly matched DataWriter asserts its liveliness or a DataWriter that was considered not alive reasserts its liveliness. It decreases every time an active DataWriter becomes not alive, either because it failed to asserts its liveliness or because it was deleted for any reason.
not_alive_count: Total number of matched DataWriters that are currently considered not alive. This count increases every time an active DataWriter becomes not alive because it fails to assert its liveliness. It decreases every time a DataWriter that was considered not alive reasserts its liveliness. Normal matching and unmatching of DataWriters does not affect this count.
alive_count_change: The change in alive_count since the last time on_liveliness_changed() was called or the status was read. It can have positive or negative values.
not_alive_count_change: The change in not_alive_count since the last time on_liveliness_changed() was called or the status was read. It can have positive or negative values.
last_publication_handle: Handle to the last DataWriter whose liveliness status was changed. If no liveliness has ever changed, it will have value c_InstanceHandle_Unknown.

3.1.3.5. RequestedDeadlineMissedStatus¶

This status changes every time the DataReader does not receive data within the deadline period configured on its DataReaderQos. See RequestedDeadlineMissedStatus.

List of status data members:

Data Member Name	Type
`total_count`	`int32_t`
`total_count_change`	`int32_t`
`last_instance_handle`	`InstanceHandle_t`

total_count: Total cumulative count of missed deadlines for any instance read by the current DataReader. As the deadline period applies to each instance of the Topic independently, the count will will be incremented by one for each instance for which data was not received in the deadline period.
total_count_change: The change in total_count since the last time on_requested_deadline_missed() was called or the status was read. It can only have zero or positive values.
last_instance_handle: Handle to the last instance that missed the deadline. If no deadline was ever missed, it will have value c_InstanceHandle_Unknown.

3.1.3.6. RequestedIncompatibleQosStatus¶

This status changes every time the DataReader finds a DataWriter that matches the Topic and has a common partition, but with a QoS configuration incompatible with the one defined on the DataReader. See RequestedIncompatibleQosStatus.

List of status data members:

Data Member Name	Type
`total_count`	`int32_t`
`total_count_change`	`int32_t`
`last_policy_id`	`QosPolicyId_t`
`policies`	`QosPolicyCountSeq`

total_count: Total cumulative count of DataWriters found matching the Topic and with a common partition, but with a QoS configuration that is incompatible with the one defined on the DataReader.
total_count_change: The change in total_count since the last time on_requested_incompatible_qos() was called or the status was read. It can only have zero or positive values.
last_policy_id: The policy ID of one of the policies that was found to be incompatible with the current DataReader. If more than one policy happens to be incompatible, only one of them will be reported in this member.
policies: A collection that holds, for each policy, the total number of times that the policy was found to be incompatible with the one offered by a remote DataWriter that matched the Topic and with a common partition. See QosPolicyCountSeq and QosPolicyCount for more information the information that is stored for each policy.

3.1.3.6.1. QosPolicyCountSeq¶

Holds a QosPolicyCount for each Policy, indexed by its QosPolicyId_t. Therefore, the Qos Policy with ID N will be at position N in the sequence. See QosPolicyCountSeq.

DataReader* data_reader =
        subscriber->create_datareader(topic, DATAREADER_QOS_DEFAULT);

// Get how many times ReliabilityQosPolicy was not compatible with a remote writer
RequestedIncompatibleQosStatus status;
data_reader->get_requested_incompatible_qos_status(status);
uint32_t incompatible_reliability_count = status.policies[RELIABILITY_QOS_POLICY_ID].count;

3.1.3.6.2. QosPolicyCount¶

This structure holds a counter for a policy. See QosPolicyCount.

List of data members:

Data Member Name	Type
`policy_id`	`QosPolicyId_t`
`count`	`int32_t`

policy_id: The ID of the policy.
count: The counter value for the policy.

3.1.3.7. SampleLostStatus¶

This status changes every time a new data sample is lost and will never be received. See SampleLostStatus.

There are two different criteria for considering a sample as lost depending on the reliability():

When using BEST_EFFORT_RELIABILITY_QOS, a not yet received sample is considered lost whenever a sample with a greater sequence number is received.
When using RELIABLE_RELIABILITY_QOS, a not yet received sample is considered lost whenever the DataWriter informs, through an RTPS HEARTBEAT submessage, that the sample is not available anymore.

List of status data members:

Data Member Name	Type
`total_count`	`int32_t`
`total_count_change`	`int32_t`

total_count: Total cumulative count of lost samples under the Topic of the current DataReader.
total_count_change: The change in total_count since the last time on_sample_lost() was called or the status was read. It can only be positive or zero.

3.1.3.8. SampleRejectedStatus¶

This status changes every time an incoming data sample is rejected by the DataReader. The reason for the rejection is defined by SampleRejectedStatusKind. For further information see SampleRejectedStatus.

List of status data members:

Data Member Name	Type
`total_count`	`int32_t`
`total_count_change`	`int32_t`
`last_reason`	`SampleRejectedStatusKind`
`last_instance_handle`	`InstanceHandle_t`

total_count: Total cumulative count of rejected samples under the Topic of the current DataReader.
total_count_change: The change in total_count since the last time on_sample_rejected() was called or the status was read. It can only be positive or zero.
last_reason: The reason for rejecting the last rejected sample. If no sample was ever rejected, it will have value NOT_REJECTED. See SampleRejectedStatusKind for further details.
last_instance_handle: Handle to the last instance whose sample was rejected. If no sample was ever rejected, it will have value c_InstanceHandle_Unknown.

3.1.3.8.1. SampleRejectedStatusKind¶

In Fast DDS, samples can be rejected due to resource limit reasons. However, the fact that the samples are rejected does not imply that they are lost, i.e. a rejected sample may be accepted in the future.

SampleRejectedStatusKind specifies the reason of the rejection:

NOT_REJECTED specifies that the samples were not rejected.
REJECTED_BY_SAMPLES_LIMIT specifies that the samples were rejected because there were not enough resources to stored them. This can happen even when there are free resources if those resources must be guaranteed to be available for other samples. This situation, which arises in the RTPS layer, occurs when there are yet to be received samples with lower sequence number and there is not enough resources for all of them (because max_samples has been reached).
REJECTED_BY_INSTANCES_LIMIT specifies that the samples were rejected because there were not enough resources to allocate the samples’ instances. This situation, which arises in the DDS layer, more precisely in the in the DataReader’s history, occurs when the sample corresponds to a new instance for which the middleware should reserve resources but the history’s number of instances has already reached max_instances.
REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT specifies that the samples were rejected because there were not enough resources within their instance to stored them. This situation, which arises in the DDS layer, more precisely in the DataReader’s history, occurs when the DataReader is configured with KEEP_ALL_HISTORY_QOS and the instance’s number of samples has reached max_samples_per_instance.

3.1.3.9. SubscriptionMatchedStatus¶

This status changes every time the DataReader finds a DataWriter that matches the Topic and has a common partition and a compatible QoS, or has ceased to be matched with a DataWriter that was previously considered to be matched. See SubscriptionMatchedStatus.

List of status data members:

Data Member Name	Type
`total_count`	`int32_t`
`total_count_change`	`int32_t`
`current_count`	`int32_t`
`current_count_change`	`int32_t`
`last_publication_handle`	`InstanceHandle_t`

total_count: Total cumulative count of remote DataWriters that have been discovered publishing on the same Topic and has a common partition and a compatible QoS. They may not all be matched at the moment.
total_count_change: The change in total_count since the last time on_subscription_matched() was called or the status was read. It can only have zero or positive values.
current_count: The number of remote DataWriters currently matched to the DataReader.
current_count_change: The change in current_count since the last time on_subscription_matched() was called or the status was read. It can have positive or negative values.
last_publication_handle: Handle to the last DataWriter that matched the DataReader. If no matching ever happened, it will have value c_InstanceHandle_Unknown.

3.1.3.10. LivelinessLostStatus¶

This status changes every time the DataWriter failed to assert its liveliness during the period configured on its DataWriterQos. This means that matched DataReader entities will consider the DataWriter as no longer alive. See LivelinessLostStatus.

List of status data members:

Data Member Name	Type
`total_count`	`int32_t`
`total_count_change`	`int32_t`

total_count: Total cumulative count of times that the DataWriter failed to assert its liveliness during the period configured on its DataWriterQos, becoming considered not alive. This count does not change when the DataWriter is already considered not alive and simply remains not alive for another liveliness period.
total_count_change: The change in total_count since the last time on_liveliness_lost() was called or the status was read. It can only have zero or positive values.

3.1.3.11. OfferedDeadlineMissedStatus¶

This status changes every time the DataWriter fails to provide data within the deadline period configured on its DataWriterQos. See OfferedDeadlineMissedStatus.

List of status data members:

Data Member Name	Type
`total_count`	`int32_t`
`total_count_change`	`int32_t`
`last_instance_handle`	`InstanceHandle_t`

total_count: Total cumulative count of missed deadlines for any instance written by the current DataWriter. As the deadline period applies to each instance of the Topic independently, the count will will be incremented by one for each instance for which data was not sent in the deadline period.
total_count_change: The change in total_count since the last time on_offered_deadline_missed() was called or the status was read. It can only have zero or positive values.
last_instance_handle: Handle to the last instance that missed the deadline. If no deadline was ever missed, it will have value c_InstanceHandle_Unknown.

3.1.3.12. OfferedIncompatibleQosStatus¶

This status changes every time the DataWriter finds a DataReader that matches the Topic and has a common partition, but with a QoS configuration that is incompatible with the one defined on the DataWriter. See OfferedIncompatibleQosStatus.

List of status data members:

Data Member Name	Type
`total_count`	`int32_t`
`total_count_change`	`int32_t`
`last_policy_id`	`QosPolicyId_t`
`policies`	`QosPolicyCountSeq`

total_count: Total cumulative count of DataReaders found matching the Topic and with a common partition, but with a QoS configuration that is incompatible with the one defined on the DataWriter.
total_count_change: The change in total_count since the last time on_offered_incompatible_qos() was called or the status was read. It can only have zero or positive values.
last_policy_id: The policy ID of one of the policies that was found to be incompatible with the current DataWriter. If more than one policy happens to be incompatible, only one of them will be reported in this member.
policies: A collection that holds, for each policy, the total number of times that the policy was found to be incompatible with the one requested by a remote DataReader that matched the Topic and with a common partition. See QosPolicyCountSeq and QosPolicyCount for more information the information that is stored for each policy.

3.1.3.13. PublicationMatchedStatus¶

This status changes every time the DataWriter finds a DataReader that matches the Topic and has a common partition and a compatible QoS, or has ceased to be matched with a DataReader that was previously considered to be matched. See PublicationMatchedStatus.

List of status data members:

Data Member Name	Type
`total_count`	`int32_t`
`total_count_change`	`int32_t`
`current_count`	`int32_t`
`current_count_change`	`int32_t`
`last_subscription_handle`	`InstanceHandle_t`

total_count: Total cumulative count of remote DataReaders that have been discovered publishing on the same Topic and has a common partition and a compatible QoS. They may not all be matched at the moment.
total_count_change: The change in total_count since the last time on_publication_matched() was called or the status was read. It can only have zero or positive values.
current_count: The number of remote DataReaders currently matched to the DataWriter.
current_count_change: The change in current_count since the last time on_publication_matched() was called or the status was read. It can have positive or negative values.
last_subscription_handle: Handle to the last DataReader that matched the DataWriter. If no matching ever happened, it will have value c_InstanceHandle_Unknown.