Status Kinds
[Infrastructure Module]

Kinds of communication status. More...


Classes
class	StatusKind
	Type for status kinds. More...
Variables
static final int	STATUS_MASK_NONE
	No bits are set.
static final int	STATUS_MASK_ALL
	All bits are set.

Detailed Description

Kinds of communication status.

Entity:: com.rti.dds.infrastructure.Entity

QoS:: QoS Policies

Listener:: com.rti.dds.infrastructure.Listener

Each concrete com.rti.dds.infrastructure.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 com.rti.dds.infrastructure.Entity.

When these status values change, the corresponding com.rti.dds.infrastructure.StatusCondition objects are activated and the proper com.rti.dds.infrastructure.Listener objects are invoked to asynchronously inform the application.

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

The statuses may be classified into:

read communication statuses: i.e., those that are related to arrival of data, namely StatusKind.DATA_ON_READERS_STATUS and StatusKind.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 (StatusKind.DATA_ON_READERS_STATUS and StatusKind.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 com.rti.dds.infrastructure.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.

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 false each time the application accesses the plain communication status via the proper get_<plain communication status>() operation on the com.rti.dds.infrastructure.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 StatusKind.REQUESTED_DEADLINE_MISSED_STATUS will become TRUE each time new deadline occurs (which increases the com.rti.dds.subscription.RequestedDeadlineMissedStatus.total_count field). The value changes to FALSE when the application accesses the status via the corresponding com.rti.dds.subscription.DataReader.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 com.rti.dds.subscription.ViewStateKind, com.rti.dds.subscription.SampleStateKind, or com.rti.dds.subscription.InstanceStateKind of any existing sample changes for any reason other than a call to com.rti.dds.topic.example.FooDataReader.read, com.rti.dds.topic.example.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 com.rti.dds.subscription.InstanceStateKind of a contained instance. This can be caused by either:
- The arrival of the notification that an instance has been disposed by:
  - the com.rti.dds.publication.DataWriter that owns it if OWNERSHIP QoS kind= OwnershipQosPolicyKind.EXCLUSIVE_OWNERSHIP_QOS
  - or by any com.rti.dds.publication.DataWriter if OWNERSHIP QoS kind= OwnershipQosPolicyKind.SHARED_OWNERSHIP_QOS
- The loss of liveliness of the com.rti.dds.publication.DataWriter of an instance for which there is no other com.rti.dds.publication.DataWriter.
- The arrival of the notification that an instance has been unregistered by the only com.rti.dds.publication.DataWriter that is known to be writing the instance.

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

The StatusKind.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 com.rti.dds.subscription.DataReader.
The StatusKind.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 com.rti.dds.subscription.DataReader belonging to the com.rti.dds.subscription.Subscriber.
- The read or take operation (or their variants) is called on any com.rti.dds.subscription.DataReader belonging to the com.rti.dds.subscription.Subscriber.

Changes in StatusChangedFlag for read communication status

See also:: com.rti.dds.infrastructure.Listener
com.rti.dds.infrastructure.WaitSet, com.rti.dds.infrastructure.Condition

Variable Documentation

final int STATUS_MASK_NONE [static, inherited]

No bits are set.

final int STATUS_MASK_ALL [static, inherited]

All bits are set.

Status Kinds [Infrastructure Module]