Specifies and configures the mechanism that allows DDS::DataReader entities to detect when DDS::DataWriter entities become disconnected or "dead.". More...

#include <managed_infrastructure.h>

Static Public Member Functions
static System::String ^	get_livelines_qos_policy_name ()
	Stringified human-readable name for DDS::LivelinessQosPolicy. More...

Public Attributes
LivelinessQosPolicyKind	kind
	The kind of liveliness desired. More...

Duration_t	lease_duration
	The duration within which a DDS::DataWriter must be asserted, or else it is assumed to be not alive. More...

System::Int32	assertions_per_lease_duration
	The number of assertions a DDS::DataWriter will send during a its DDS::LivelinessQosPolicy::lease_duration. More...

Detailed Description

Specifies and configures the mechanism that allows DDS::DataReader entities to detect when DDS::DataWriter entities become disconnected or "dead.".

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

A DDS::DataWriter commits to signalling its liveliness at intervals not to exceed the DDS::LivelinessQosPolicy::lease_duration configured on the DDS::DataWriter. The rate at which the DDS::DataWriter will signal its liveliness is defined by DDS::LivelinessQosPolicy::assertions_per_lease_duration.

The DDS::DataReader lease_duration specifies the maximum period at which matching DataWriters must have their liveliness asserted.

In addition, in the subscribing application Connext DDS uses an internal thread that wakes up at the period set by the DataReader's lease_duration to see if a DataWriter lease_duration has been violated.

Important: A DataReader will consider a DataWriter not alive if the DataWriter does not assert its liveliness within the DataWriter lease_duration not the DataReader lease_duration.

Listeners are used to notify a DDS::DataReader of loss of liveliness and DDS::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 DDS::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, DDS::DataReader, DDS::DataWriter

Status:: DDS::StatusKind::LIVELINESS_LOST_STATUS, DDS::LivelinessLostStatus;
DDS::StatusKind::LIVELINESS_CHANGED_STATUS, DDS::LivelinessChangedStatus;
DDS::StatusKind::REQUESTED_INCOMPATIBLE_QOS_STATUS, DDS::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 DataWriters 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::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 DDS::DomainParticipant is running and the link connecting it to remote participants remains connected, the entities within the DDS::DomainParticipant will be considered alive. This requires the lowest overhead.

The manual settings (DDS::LivelinessQosPolicyKind::MANUAL_BY_PARTICIPANT_LIVELINESS_QOS, DDS::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 DDS::Entity is still alive. The action can be explicit by calling the DDS::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::LivelinessQosPolicyKind::MANUAL_BY_PARTICIPANT_LIVELINESS_QOS requires only that one DDS::Entity within a participant is asserted to be alive to deduce all other DDS::Entity objects within the same DDS::DomainParticipant are also alive.

The setting DDS::LivelinessQosPolicyKind::MANUAL_BY_TOPIC_LIVELINESS_QOS requires that at least one instance within the DDS::DataWriter is asserted.

Changes in LIVELINESS must be detected by the Service with a time-granularity greater or equal to the DDS::LivelinessQosPolicy::lease_duration. This ensures that the value of the DDS::LivelinessChangedStatus is updated at least once during each lease_duration and the related Listeners and DDS::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 DDS::LivelinessQosPolicyKind kind are considered ordered such that: DDS::LivelinessQosPolicyKind::AUTOMATIC_LIVELINESS_QOS < DDS::LivelinessQosPolicyKind::MANUAL_BY_PARTICIPANT_LIVELINESS_QOS < DDS::LivelinessQosPolicyKind::MANUAL_BY_TOPIC_LIVELINESS_QOS.
the inequality offered lease_duration <= requested lease_duration evaluates to true.

See also: Relationship between registration, liveliness and ownership

Member Data Documentation

◆ kind

LivelinessQosPolicyKind DDS::LivelinessQosPolicy::kind

The kind of liveliness desired.

[default] DDS::LivelinessQosPolicyKind::AUTOMATIC_LIVELINESS_QOS

◆ lease_duration

Duration_t DDS::LivelinessQosPolicy::lease_duration

The duration within which a DDS::DataWriter must be asserted, or else it is assumed to be not alive.

For a DataWriter, the lease_duration specifies a timeout by which liveliness must be asserted for the DataWriter or the DataWriter will be considered inactive or not alive.

For a DataReader, the lease_duration specifies the maximum period at which the DataReader will check to see if the matching DataWriters are still alive according to the DataWriters lease_duration value.

Important: A DataReader will consider a DataWriter not alive if it does not assert its liveliness within the DataWriter lease_duration not the DataReader lease_duration.

[default] DDS::Duration_t::DURATION_INFINITE

[range] [0,1 year] or DDS::Duration_t::DURATION_INFINITE

◆ assertions_per_lease_duration

System::Int32 DDS::LivelinessQosPolicy::assertions_per_lease_duration

The number of assertions a DDS::DataWriter will send during a its DDS::LivelinessQosPolicy::lease_duration.

This field only applies to a DDS::DataWriter and is not considered during QoS compatibility checks.

The default value is 3. A higher value will make the liveliness mechanism more robust against packet losses, but it will also increase the network traffic.

[default] 3

[range] [2, 100 million]

Static Public Member Functions