RTI Connext Modern C++ API  Version 5.2.0
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
dds::core::policy::Liveliness Class Reference

Specifies and configures the mechanism that allows dds::sub::DataReader's to detect when dds::pub::DataWriter's become disconnected. More...

#include <dds/core/policy/CorePolicy.hpp>

Public Member Functions

 Liveliness ()
 Creates an automatic liveliness policy with infinite lease duration.
 
 Liveliness (dds::core::policy::LivelinessKind the_kind, const dds::core::Duration &the_lease_duration)
 Creates an instance with the specified liveliness kind and lease duration.
 
Livelinesskind (dds::core::policy::LivelinessKind the_kind)
 Sets the liveliness kind.
 
dds::core::policy::LivelinessKind kind () const
 Getter (see the setter with the same name)
 
Livelinesslease_duration (const dds::core::Duration &the_lease_duration)
 Sets the duration within which a dds::core::Entity must be asserted or else it is considered not alive.
 
dds::core::Duration lease_duration () const
 Getter (see the setter with the same name)
 

Static Public Member Functions

static Liveliness Automatic ()
 Creates a Liveliness instance with LivelinessKind::AUTOMATIC.
 
static Liveliness ManualByParticipant (const dds::core::Duration &lease=dds::core::Duration::infinite())
 Creates a Liveliness instance with LivelinessKind::MANUAL_BY_PARTICIPANT and the specified lease duration (infinite by default)
 
static Liveliness ManualByTopic (const dds::core::Duration &lease=dds::core::Duration::infinite())
 Creates a Liveliness instance with LivelinessKind::MANUAL_BY_TOPIC and the specified lease duration (infinite by default)
 

Detailed Description

Specifies and configures the mechanism that allows dds::sub::DataReader's to detect when dds::pub::DataWriter's become disconnected.

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

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

A dds::sub::DataReader requests that liveliness of writers is maintained by the requested means and loss of liveliness is detected with delay not to exceed the dds::core::policy::Liveliness::lease_duration.

A dds::pub::DataWriter commits to signalling its liveliness using the stated means at intervals not to exceed the dds::core::policy::Liveliness::lease_duration. The rate at which the dds::pub::DataWriter will signal its liveliness is defined by dds::core::policy::Liveliness::assertions_per_lease_duration.

Listeners are used to notify a dds::sub::DataReader of loss of liveliness and dds::pub::DataWriter of violations to the liveliness contract. The on_liveliness_lost() callback is only called once, after the first time the dds::core::policy::Liveliness::lease_duration is exceeded (when the dds::pub::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:
dds::topic::Topic, dds::sub::DataReader, dds::pub::DataWriter
Status:
dds::core::status::StatusMask::liveliness_lost(), dds::core::status::LivelinessLostStatus;
dds::core::status::StatusMask::liveliness_changed(), dds::core::status::LivelinessChangedStatus;
dds::core::status::StatusMask::requested_incompatible_qos(), dds::core::status::StatusMask::offered_incompatible_qos()
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 dds::core::policy::LivelinessKind::AUTOMATIC 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 dds::domain::DomainParticipant is running and the link connecting it to remote participants remains connected, the entities within the dds::domain::DomainParticipant will be considered alive. This requires the lowest overhead.

The manual settings (dds::core::policy::LivelinessKind::MANUAL_BY_PARTICIPANT, dds::core::policy::LivelinessKind::MANUAL_BY_TOPIC) require the application on the publishing side to periodically assert the liveliness before the lease expires to indicate the corresponding dds::core::Entity is still alive. The action can be explicit by calling the dds::pub::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 dds::core::policy::LivelinessKind::MANUAL_BY_TOPIC requires that at least one instance within the dds::pub::DataWriter is asserted.

Changes in LIVELINESS must be detected by the Service with a time-granularity greater or equal to the dds::core::policy::Liveliness::lease_duration. This ensures that the value of the dds::core::status::LivelinessChangedStatus is updated at least once during each dds::core::policy::Liveliness::lease_duration and the related Listeners and dds::core::cond::WaitSet s are notified within a dds::core::policy::Liveliness::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 dds::core::policy::LivelinessKind kind are considered ordered such that: dds::core::policy::LivelinessKind::AUTOMATIC < dds::core::policy::LivelinessKind::MANUAL_BY_PARTICIPANT < dds::core::policy::LivelinessKind::MANUAL_BY_TOPIC.
  • the inequality offered lease_duration <= requested lease_duration evaluates to true.
See Also
Relationship between registration, liveliness and ownership The need for registering/unregistering instances stems from two use cases:
  • Ownership resolution on redundant systems
  • Detection of loss in topological connectivity
These two use cases also illustrate the semantic differences between the dds::pub::DataWriter::unregister_instance and dds::pub::DataWriter::dispose_instance(). BROKEN_SECTIONS

Constructor & Destructor Documentation

dds::core::policy::Liveliness::Liveliness ( )
inline

Creates an automatic liveliness policy with infinite lease duration.

dds::core::policy::Liveliness::Liveliness ( dds::core::policy::LivelinessKind  the_kind,
const dds::core::Duration the_lease_duration 
)
inline

Creates an instance with the specified liveliness kind and lease duration.

Member Function Documentation

Liveliness& dds::core::policy::Liveliness::kind ( dds::core::policy::LivelinessKind  the_kind)
inline

Sets the liveliness kind.

[default] dds::core::policy::LivelinessKind::AUTOMATIC

dds::core::policy::LivelinessKind dds::core::policy::Liveliness::kind ( ) const
inline

Getter (see the setter with the same name)

Liveliness& dds::core::policy::Liveliness::lease_duration ( const dds::core::Duration the_lease_duration)
inline

Sets the duration within which a dds::core::Entity must be asserted or else it is considered not alive.

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

[default] dds::core::Duration::infinite()

[range] [0,1 year] or dds::core::Duration::infinite()

dds::core::Duration dds::core::policy::Liveliness::lease_duration ( ) const
inline

Getter (see the setter with the same name)

static Liveliness dds::core::policy::Liveliness::Automatic ( )
inlinestatic

Creates a Liveliness instance with LivelinessKind::AUTOMATIC.

static Liveliness dds::core::policy::Liveliness::ManualByParticipant ( const dds::core::Duration lease = dds::core::Duration::infinite())
inlinestatic

Creates a Liveliness instance with LivelinessKind::MANUAL_BY_PARTICIPANT and the specified lease duration (infinite by default)

static Liveliness dds::core::policy::Liveliness::ManualByTopic ( const dds::core::Duration lease = dds::core::Duration::infinite())
inlinestatic

Creates a Liveliness instance with LivelinessKind::MANUAL_BY_TOPIC and the specified lease duration (infinite by default)


RTI Connext Modern C++ API Version 5.2.0 Copyright © Sun Jun 21 2015 Real-Time Innovations, Inc