RTI Connext Java API  Version 5.0.0
LivelinessQosPolicy Class Reference

Specifies and configures the mechanism that allows com.rti.dds.subscription.DataReader entities to detect when com.rti.dds.publication.DataWriter entities become disconnected or "dead.". More...

Inheritance diagram for LivelinessQosPolicy:
QosPolicy

Public Attributes

LivelinessQosPolicyKind kind
 The kind of liveliness desired.
 
final Duration_t lease_duration
 The duration within which a com.rti.dds.infrastructure.Entity must be asserted, or else it is assumed to be not alive.
 
- Public Attributes inherited from QosPolicy
final QosPolicyId_t id
 The ID of this QoS policy.
 
final String policy_name
 The name of this QoS policy.
 

Additional Inherited Members

- Public Member Functions inherited from Struct
abstract boolean equals (Object obj)
 
abstract int hashCode ()
 
String toString ()
 
- Protected Member Functions inherited from Struct
 Struct ()
 
abstract void pull_from_nativeI (long native_status)
 
abstract void push_to_nativeI (long native_status)
 

Detailed Description

Specifies and configures the mechanism that allows com.rti.dds.subscription.DataReader entities to detect when com.rti.dds.publication.DataWriter entities become disconnected or "dead.".

Liveliness must be asserted at least once every lease_duration otherwise RTI Connext will assume the corresponding com.rti.dds.infrastructure.Entity or is no longer alive.

The liveliness status of a com.rti.dds.infrastructure.Entity is used to maintain instance ownership in combination with the setting of the OWNERSHIP policy. The application is also informed via com.rti.dds.infrastructure.Listener when an com.rti.dds.infrastructure.Entity is no longer alive.

A com.rti.dds.subscription.DataReader requests that liveliness of writers is maintained by the requested means and loss of liveliness is detected with delay not to exceed the lease_duration.

A com.rti.dds.publication.DataWriter commits to signalling its liveliness using the stated means at intervals not to exceed the lease_duration.

Listeners are used to notify a com.rti.dds.subscription.DataReader of loss of liveliness and com.rti.dds.publication.DataWriter of violations to the liveliness contract. The on_liveliness_lost() callback is only called once, after the first time the lease_duration is exceeded (when the com.rti.dds.publication.DataWriter first loses liveliness).

This QoS policy can be used during system integration to ensure that applications have been coded to meet design specifications. It can also be used during run time to detect when systems are performing outside of design specifications. Receiving applications can take appropriate actions in response to disconnected DataWriters.

Entity:
com.rti.dds.topic.Topic, com.rti.dds.subscription.DataReader, com.rti.dds.publication.DataWriter
Status:
com.rti.dds.infrastructure.StatusKind.StatusKind.LIVELINESS_LOST_STATUS, com.rti.dds.publication.LivelinessLostStatus;
com.rti.dds.infrastructure.StatusKind.StatusKind.LIVELINESS_CHANGED_STATUS, com.rti.dds.subscription.LivelinessChangedStatus;
com.rti.dds.infrastructure.StatusKind.StatusKind.REQUESTED_INCOMPATIBLE_QOS_STATUS, com.rti.dds.infrastructure.StatusKind.StatusKind.OFFERED_INCOMPATIBLE_QOS_STATUS
Properties:
RxO = YES
Changeable = UNTIL ENABLE

Usage

This policy controls the mechanism and parameters used by RTI Connext to ensure that particular entities on the network are still alive. The liveliness can also affect the ownership of a particular instance, as determined by the OWNERSHIP policy.

This policy has several settings to support both data types that are updated periodically as well as those that are changed sporadically. It also allows customisation for different application requirements in terms of the kinds of failures that will be detected by the liveliness mechanism.

The com.rti.dds.infrastructure.LivelinessQosPolicyKind.LivelinessQosPolicyKind.AUTOMATIC_LIVELINESS_QOS liveliness setting is most appropriate for applications that only need to detect failures at the process-level, but not application-logic failures within a process. RTI Connext takes responsibility for renewing the leases at the required rates and thus, as long as the local process where a com.rti.dds.domain.DomainParticipant is running and the link connecting it to remote participants remains connected, the entities within the com.rti.dds.domain.DomainParticipant will be considered alive. This requires the lowest overhead.

The manual settings (com.rti.dds.infrastructure.LivelinessQosPolicyKind.LivelinessQosPolicyKind.MANUAL_BY_PARTICIPANT_LIVELINESS_QOS, com.rti.dds.infrastructure.LivelinessQosPolicyKind.LivelinessQosPolicyKind.MANUAL_BY_TOPIC_LIVELINESS_QOS) require the application on the publishing side to periodically assert the liveliness before the lease expires to indicate the corresponding com.rti.dds.infrastructure.Entity is still alive. The action can be explicit by calling the com.rti.dds.publication.DataWriter.assert_liveliness operation or implicit by writing some data.

The two possible manual settings control the granularity at which the application must assert liveliness.

  • The setting com.rti.dds.infrastructure.LivelinessQosPolicyKind.LivelinessQosPolicyKind.MANUAL_BY_TOPIC_LIVELINESS_QOS requires that at least one instance within the com.rti.dds.publication.DataWriter is asserted.

Changes in LIVELINESS must be detected by the Service with a time-granularity greater or equal to the lease_duration. This ensures that the value of the com.rti.dds.subscription.LivelinessChangedStatus is updated at least once during each lease_duration and the related Listeners and com.rti.dds.infrastructure.WaitSet s are notified within a lease_duration from the time the LIVELINESS changed.

Compatibility

The value offered is considered compatible with the value requested if and only if the following conditions are met:

  • the inequality offered kind >= requested kind evaluates to 'TRUE'. For the purposes of this inequality, the values of com.rti.dds.infrastructure.LivelinessQosPolicyKind kind are considered ordered such that: com.rti.dds.infrastructure.LivelinessQosPolicyKind.LivelinessQosPolicyKind.AUTOMATIC_LIVELINESS_QOS < com.rti.dds.infrastructure.LivelinessQosPolicyKind.LivelinessQosPolicyKind.MANUAL_BY_PARTICIPANT_LIVELINESS_QOS < com.rti.dds.infrastructure.LivelinessQosPolicyKind.LivelinessQosPolicyKind.MANUAL_BY_TOPIC_LIVELINESS_QOS.
  • the inequality offered lease_duration <= requested lease_duration evaluates to com.rti.dds.infrastructure.true.
See Also
RELATIONSHIP BETWEEN REGISTRATION, LIVELINESS and OWNERSHIP

Member Data Documentation

The kind of liveliness desired.

[default] com.rti.dds.infrastructure.LivelinessQosPolicyKind.LivelinessQosPolicyKind.AUTOMATIC_LIVELINESS_QOS

final Duration_t lease_duration

The duration within which a com.rti.dds.infrastructure.Entity must be asserted, or else it is assumed to be not alive.

[default] com.rti.dds.infrastructure.Duration_t.INFINITE

[range] [0,1 year] or com.rti.dds.infrastructure.Duration_t.INFINITE


RTI Connext Java API Version 5.0.0 Copyright © Thu Aug 30 2012 Real-Time Innovations, Inc