RTI Connext .NET API (legacy)
Version 6.1.2
|
Kinds of communication status. More...
Kinds of communication status.
Each concrete DDS::Entity is associated with a set of Status objects whose value represents the communication status of that entity. Each status value can be accessed with a corresponding method on the DDS::Entity.
When these status values change, the corresponding DDS::StatusCondition objects are activated and the proper DDS::Listener objects are invoked to asynchronously inform the application.
An application is notified of communication status by means of the DDS::Listener or the DDS::WaitSet / DDS::Condition mechanism. The two mechanisms may be combined in the application (e.g., using DDS::WaitSet (s) / DDS::Condition (s) to access the data and DDS::Listener (s) to be warned asynchronously of erroneous communication statuses).
It is likely that the application will choose one or the other mechanism for each particular communication status (not both). However, if both mechanisms are enabled, then the DDS::Listener mechanism is used first and then the DDS::WaitSet objects are signalled.
The statuses may be classified into:
Read communication statuses are treated slightly differently than the others because they don't change independently. In other words, at least two changes will appear at the same time (DATA_ON_READERS_STATUS and DATA_AVAILABLE_STATUS) and even several of the last kind may be part of the set. This 'grouping' has to be communicated to the application.
For each plain communication status, there is a corresponding structure to hold the status value. These values contain the information related to the change of status, as well as information related to the statuses themselves (e.g., contains cumulative counts).
Associated with each one of an DDS::Entity's communication status is a logical 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 status changes is slightly different for the Plain Communication Status and the Read 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 it is reset to false each time the application accesses the plain communication status via the proper get_<plain communication status>()
operation on the DDS::Entity.
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_<plain communication status> 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 NOOP and the act of calling the 'nil' listener does not reset the communication status.
For example, the value of the StatusChangedFlag
associated with the REQUESTED_DEADLINE_MISSED_STATUS will become TRUE each time new deadline occurs (which increases DDS::RequestedDeadlineMissedStatus::total_count). The value changes to FALSE when the application accesses the status via the corresponding DDS::DataReader::get_requested_deadline_missed_status method on the proper Entity
For the read communication status, the StatusChangedFlag
flag is initially set to FALSE. The StatusChangedFlag
becomes TRUE when either a data-sample arrives or else the DDS::ViewStateKind, DDS::SampleStateKind, or DDS::InstanceStateKind of any existing sample changes for any reason other than a call to DDS::TypedDataReader::read, DDS::TypedDataReader::take or their variants. Specifically any of the following events will cause the StatusChangedFlag
to become TRUE:
The arrival of new data.
A change in the DDS::InstanceStateKind of a contained instance. This can be caused by either:
Depending on the kind of StatusChangedFlag
, the flag transitions to FALSE again as follows:
StatusChangedFlag
becomes FALSE when either the corresponding listener operation (on_data_available) is called or the read or take operation (or their variants) is called on the associated DDS::DataReader. StatusChangedFlag
becomes FALSE when any of the following events occurs:
|
strong |
A bit-mask (list) of concrete status types, i.e. DDS::StatusKind[].
The bit-mask is an efficient and compact representation of a fixed-length list of DDS::StatusKind values.
Bits in the mask correspond to different statuses. You can choose which changes in status will trigger a callback by setting the corresponding status bits in this bit-mask and installing callbacks for each of those statuses.
The bits that are true indicate that the listener will be called back for changes in the corresponding status.
If you want to listen for specific statuses (not DDS::StatusMask::STATUS_MASK_ALL or DDS::StatusMask::STATUS_MASK_NONE), you must cast StatusKind to a StatusMask. The following example shows how to do so:
Enumerator | |
---|---|
STATUS_MASK_NONE | No bits are set. |
STATUS_MASK_ALL | All bits are set. |
|
strong |
Type for status kinds.
Each concrete DDS::Entity is associated with a set of *Status
objects whose values represent the communication status of that DDS::Entity.
The communication statuses whose changes can be communicated to the application depend on the DDS::Entity.
Each status value can be accessed with a corresponding method on the DDS::Entity. The changes on these status values cause activation of the corresponding DDS::StatusCondition objects and trigger invocation of the proper DDS::Listener objects to asynchronously inform the application. Note that not all statuses will activate the DDS::StatusCondition or have a corresponding listener callback. Refer to the documentation of the individual statuses for that information.
If you want to listen for specific statuses (not DDS::StatusMask::STATUS_MASK_ALL or DDS::StatusMask::STATUS_MASK_NONE), you must cast StatusKind to a StatusMask. The following example shows how to do so:
Enumerator | |
---|---|
INCONSISTENT_TOPIC_STATUS | Another topic exists with the same name but different characteristics.
|
OFFERED_DEADLINE_MISSED_STATUS | The deadline that the DDS::DataWriter has committed through its DDS::DeadlineQosPolicy was not respected for a specific instance.
|
REQUESTED_DEADLINE_MISSED_STATUS | The deadline that the DDS::DataReader was expecting through its DDS::DeadlineQosPolicy was not respected for a specific instance.
|
OFFERED_INCOMPATIBLE_QOS_STATUS | A QosPolicy value was incompatible with what was requested.
|
REQUESTED_INCOMPATIBLE_QOS_STATUS | A QosPolicy value was incompatible with what is offered.
|
SAMPLE_LOST_STATUS | A sample has been lost (i.e., was never received).
|
SAMPLE_REJECTED_STATUS | A (received) sample has been rejected.
|
DATA_ON_READERS_STATUS | New data is available.
|
DATA_AVAILABLE_STATUS | One or more new data samples have been received.
|
LIVELINESS_LOST_STATUS | The liveliness that the DDS::DataWriter has committed to through its DDS::LivelinessQosPolicy was not respected, thus DDS::DataReader entities will consider the DDS::DataWriter as no longer alive.
|
LIVELINESS_CHANGED_STATUS | The liveliness of one or more DDS::DataWriter that were writing instances read through the DDS::DataReader has changed. Some DDS::DataWriter have become alive or not_alive.
|
PUBLICATION_MATCHED_STATUS | The DDS::DataWriter has found DDS::DataReader that matches the DDS::Topic and has compatible QoS.
|
SUBSCRIPTION_MATCHED_STATUS | The DDS::DataReader has found DDS::DataWriter that matches the DDS::Topic and has compatible QoS.
|
SERVICE_REQUEST_ACCEPTED_STATUS | <<extension>> A DDS::DataWriter has been issued a DDS::ServiceRequest Enables a DDS::DataWriter callback that is called when a DDS::ServiceRequest has been accepted and dispatched to the DataWriter.
|
DATA_WRITER_APPLICATION_ACKNOWLEDGMENT_STATUS | <<extension>> A DDS::DataWriter has received an application-level acknowledgment for a sample Enables a DDS::DataWriter callback that is called when an application-level acknowledgment from a DDS::DataReader is received. The callback is called for each sample that is application-level acknowledged. Changes to this status do not trigger a DDS::StatusCondition.
|
DATA_WRITER_INSTANCE_REPLACED_STATUS | <<extension>> A DDS::DataWriter instance has been replaced Enables a DDS::DataWriter callback that is called when an instance in the writer queue is replaced.
|
RELIABLE_WRITER_CACHE_CHANGED_STATUS | <<extension>> The number of unacknowledged samples in a reliable writer's cache has changed such that it has reached a pre-defined trigger point. This status is considered changed at the following times: the cache is empty (i.e. contains no unacknowledge samples), full (i.e. the sample count has reached the value specified in DDS::ResourceLimitsQosPolicy::max_samples), or the number of samples has reached a high (see DDS::RtpsReliableWriterProtocol_t::high_watermark) or low (see DDS::RtpsReliableWriterProtocol_t::low_watermark) watermark.
|
RELIABLE_READER_ACTIVITY_CHANGED_STATUS | <<extension>> One or more reliable readers has become active or inactive. A reliable reader is considered active by a reliable writer with which it is matched if that reader acknowledges the samples it has been sent in a timely fashion. For the definition of "timely" in this case, see DDS::RtpsReliableWriterProtocol_t and DDS::ReliableReaderActivityChangedStatus. |
DATA_WRITER_CACHE_STATUS | <<extension>> The status of the writer's cache. Changes to this status do not trigger a DDS::StatusCondition. |
DATA_WRITER_PROTOCOL_STATUS | <<extension>> The status of a writer's internal protocol related metrics The status of a writer's internal protocol-related metrics, such as the number of samples pushed, pulled, and filtered and the status of wire protocol traffic. Changes to this status information do not trigger a DDS::StatusCondition. |
DATA_READER_CACHE_STATUS | <<extension>> The status of the reader's cache. Changes to this status do not trigger a DDS::StatusCondition. |
DATA_READER_PROTOCOL_STATUS | <<extension>> The status of a reader's internal protocol related metrics The status of a reader's internal protocol related metrics, like the number of samples received, filtered, rejected; and status of wire protocol traffic. Changes to this status do not trigger a DDS::StatusCondition. |