Status Kinds
[Infrastructure Module]

Kinds of communication status. More...


Defines
#define	DDS_STATUS_MASK_NONE
	No bits are set.
#define	DDS_STATUS_MASK_ALL
	All bits are set.
Typedefs
typedef DDS_UnsignedLong	DDS_StatusMask
	A bit-mask (list) of concrete status types, i.e. DDS_StatusKind[].
Enumerations
enum	DDS_StatusKind { DDS_INCONSISTENT_TOPIC_STATUS, DDS_OFFERED_DEADLINE_MISSED_STATUS, DDS_REQUESTED_DEADLINE_MISSED_STATUS, DDS_OFFERED_INCOMPATIBLE_QOS_STATUS, DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS, DDS_SAMPLE_LOST_STATUS, DDS_SAMPLE_REJECTED_STATUS, DDS_DATA_ON_READERS_STATUS, DDS_DATA_AVAILABLE_STATUS, DDS_LIVELINESS_LOST_STATUS, DDS_LIVELINESS_CHANGED_STATUS, DDS_PUBLICATION_MATCHED_STATUS, DDS_SUBSCRIPTION_MATCHED_STATUS , DDS_RELIABLE_WRITER_CACHE_CHANGED_STATUS, DDS_RELIABLE_READER_ACTIVITY_CHANGED_STATUS, DDS_DATA_WRITER_CACHE_STATUS, DDS_DATA_WRITER_PROTOCOL_STATUS, DDS_DATA_READER_CACHE_STATUS, DDS_DATA_READER_PROTOCOL_STATUS }
	Type for status kinds. More...

Detailed Description

Kinds of communication status.

Entity:: DDSEntity

QoS:: QoS Policies

Listener:: DDSListener

Each concrete DDSEntity 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 DDSEntity.

When these status values change, the corresponding DDSStatusCondition objects are activated and the proper DDSListener objects are invoked to asynchronously inform the application.

An application is notified of communication status by means of the DDSListener or the DDSWaitSet / DDSCondition mechanism. The two mechanisms may be combined in the application (e.g., using DDSWaitSet (s) / DDSCondition (s) to access the data and DDSListener (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 DDSListener mechanism is used first and then the DDSWaitSet objects are signalled.

The statuses may be classified into:

read communication statuses: i.e., those that are related to arrival of data, namely DDS_DATA_ON_READERS_STATUS and DDS_DATA_AVAILABLE_STATUS.

plain communication statuses: i.e., all the others.

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 (DDS_DATA_ON_READERS_STATUS and DDS_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).

Status Values

Changes in Status

Associated with each one of an DDSEntity'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.

StatusChangedFlag indicates if status has changed

Changes in 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 it is reset to DDS_BOOLEAN_FALSE each time the application accesses the plain communication status via the proper get_<plain communication status>() operation on the DDSEntity.

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 DDS_REQUESTED_DEADLINE_MISSED_STATUS will become TRUE each time new deadline occurs (which increases the DDS_RequestedDeadlineMissedStatus::total_count field). The value changes to FALSE when the application accesses the status via the corresponding DDSDataReader::get_requested_deadline_missed_status method on the proper Entity

Changes in StatusChangedFlag for plain communication status

Changes in read communication status

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 FooDataReader::read, FooDataReader::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:
- The arrival of the notification that an instance has been disposed by:
  - the DDSDataWriter that owns it if OWNERSHIP QoS kind= DDS_EXCLUSIVE_OWNERSHIP_QOS
  - or by any DDSDataWriter if OWNERSHIP QoS kind= DDS_SHARED_OWNERSHIP_QOS
- The loss of liveliness of the DDSDataWriter of an instance for which there is no other DDSDataWriter.
- The arrival of the notification that an instance has been unregistered by the only DDSDataWriter that is known to be writing the instance.

Depending on the kind of StatusChangedFlag, the flag transitions to FALSE again as follows:

The DDS_DATA_AVAILABLE_STATUS 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 DDSDataReader.
The DDS_DATA_ON_READERS_STATUS StatusChangedFlag becomes FALSE when any of the following events occurs:
- The corresponding listener operation (on_data_on_readers) is called.
- The on_data_available listener operation is called on any DDSDataReader belonging to the DDSSubscriber.
- The read or take operation (or their variants) is called on any DDSDataReader belonging to the DDSSubscriber.

Changes in StatusChangedFlag for read communication status

See also:: DDSListener
DDSWaitSet, DDSCondition

Define Documentation

#define DDS_STATUS_MASK_NONE

No bits are set.

Examples:: HelloWorld_publisher.cxx, and HelloWorld_subscriber.cxx.

#define DDS_STATUS_MASK_ALL

All bits are set.

Examples:: HelloWorld_subscriber.cxx.

Typedef Documentation

typedef DDS_UnsignedLong DDS_StatusMask

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.

For example:

 DDS_StatusMask mask = DDS_REQUESTED_DEADLINE_MISSED_STATUS | 
                                      DDS_DATA_AVAILABLE_STATUS; 
                  datareader->set_listener(listener, mask);

or

 DDS_StatusMask mask = DDS_REQUESTED_DEADLINE_MISSED_STATUS | 
                                      DDS_DATA_AVAILABLE_STATUS; 
                  datareader = subscriber->create_datareader(topic, 
                                                 DDS_DATAREADER_QOS_DEFAULT, 
                                                 listener, mask);

Enumeration Type Documentation

enum DDS_StatusKind

Type for status kinds.

Each concrete DDSEntity is associated with a set of *Status objects whose values represent the communication status of that DDSEntity.

The communication statuses whose changes can be communicated to the application depend on the DDSEntity.

Each status value can be accessed with a corresponding method on the DDSEntity. The changes on these status values cause activation of the corresponding DDSStatusCondition objects and trigger invocation of the proper DDSListener objects to asynchronously inform the application.

See also:: DDSEntity, DDSStatusCondition, DDSListener

Enumerator:

DDS_INCONSISTENT_TOPIC_STATUS	Another topic exists with the same name but different characteristics. Entity: DDSTopic Status: DDS_InconsistentTopicStatus Listener: DDSTopicListener
DDS_OFFERED_DEADLINE_MISSED_STATUS	The deadline that the DDSDataWriter has committed through its DDS_DeadlineQosPolicy was not respected for a specific instance. Entity: DDSDataWriter QoS: DEADLINE Status: DDS_OfferedDeadlineMissedStatus Listener: DDSDataWriterListener
DDS_REQUESTED_DEADLINE_MISSED_STATUS	The deadline that the DDSDataReader was expecting through its DDS_DeadlineQosPolicy was not respected for a specific instance. Entity: DDSDataReader QoS: DEADLINE Status: DDS_RequestedDeadlineMissedStatus Listener: DDSDataReaderListener
DDS_OFFERED_INCOMPATIBLE_QOS_STATUS	A QosPolicy value was incompatible with what was requested. Entity: DDSDataWriter Status: DDS_OfferedIncompatibleQosStatus Listener: DDSDataWriterListener
DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS	A QosPolicy value was incompatible with what is offered. Entity: DDSDataReader Status: DDS_RequestedIncompatibleQosStatus Listener: DDSDataReaderListener
DDS_SAMPLE_LOST_STATUS	A sample has been lost (i.e. was never received). Entity: DDSSubscriber Status: DDS_SampleLostStatus Listener: DDSSubscriberListener
DDS_SAMPLE_REJECTED_STATUS	A (received) sample has been rejected. Entity: DDSDataReader QoS: RESOURCE_LIMITS Status: DDS_SampleRejectedStatus Listener: DDSDataReaderListener
DDS_DATA_ON_READERS_STATUS	New data is available. Entity: DDSSubscriber Listener: DDSSubscriberListener
DDS_DATA_AVAILABLE_STATUS	One or more new data samples have been received. Entity: DDSDataReader Listener: DDSDataReaderListener
DDS_LIVELINESS_LOST_STATUS	The liveliness that the DDSDataWriter has committed to through its DDS_LivelinessQosPolicy was not respected, thus DDSDataReader entities will consider the DDSDataWriter as no longer alive. Entity: DDSDataWriter QoS: LIVELINESS Status: DDS_LivelinessLostStatus Listener: DDSDataWriterListener
DDS_LIVELINESS_CHANGED_STATUS	The liveliness of one or more DDSDataWriter that were writing instances read through the DDSDataReader has changed. Some DDSDataWriter have become alive or not_alive. Entity: DDSDataReader QoS: LIVELINESS Status: DDS_LivelinessChangedStatus Listener: DDSDataReaderListener
DDS_PUBLICATION_MATCHED_STATUS	The DDSDataWriter has found DDSDataReader that matches the DDSTopic and has compatible QoS. Entity: DDSDataWriter Status: DDS_PublicationMatchedStatus Listener: DDSDataWriterListener
DDS_SUBSCRIPTION_MATCHED_STATUS	The DDSDataReader has found DDSDataWriter that matches the DDSTopic and has compatible QoS. Entity: DDSDataReader Status: DDS_SubscriptionMatchedStatus Listener: DDSDataReaderListener
DDS_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. Entity: DDSDataWriter Status: DDS_ReliableWriterCacheChangedStatus Listener: DDSDataWriterListener
DDS_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. See also: DDS_RtpsReliableWriterProtocol_t DDS_ReliableReaderActivityChangedStatus
DDS_DATA_WRITER_CACHE_STATUS	<<eXtension>> The status of the writer's cache.
DDS_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, like the number of samples pushed, pulled, filtered; and status of wire protocol traffic.
DDS_DATA_READER_CACHE_STATUS	<<eXtension>> The status of the reader's cache.
DDS_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.

Status Kinds [Infrastructure Module]

Defines

Typedefs

Enumerations