You are here: Part 2: Core Concepts > Sending Data > DataWriter QosPolicies > LIVELINESS QosPolicy

LIVELINESS QosPolicy

The LIVELINESS QosPolicy specifies how Connext DDS determines whether a DataWriter is “alive.” A DataWriter’s liveliness is used in combination with the OWNERSHIP QosPolicy to maintain ownership of an instance (note that the DEADLINE QosPolicy is also used to change ownership when a DataWriter is still alive). That is, for a DataWriter to own an instance, the DataWriter must still be alive as well as honoring its DEADLINE contract.

It includes the members in Table 49 . For defaults and valid ranges, please refer to the API Reference HTML documentation.

Table 49 DDS_LivelinessQosPolicy

Type

Field Name

Description

DDS_LivelinessQosPolicyKind

kind

DDS_AUTOMATIC_LIVELINESS_QOS:
Connext DDS will automatically assert liveliness for the DataWriter at least as often as the lease_duration.

DDS_MANUAL_BY_PARTICIPANT_LIVELINESS_QOS:
The DataWriter is assumed to be alive if any Entity within the same DomainParticipant has asserted its liveliness.

DDS_MANUAL_BY_TOPIC_LIVELINESS_QOS:
Your application must explicitly assert the liveliness of the DataWriter within the lease_duration.

DDS_Duration_t

lease_duration

The timeout by which liveliness must be asserted for the DataWriter or the DataWriter will be considered inactive or not alive.

Additionally, for DataReaders, the lease_duration also specifies the maximum period at which Connext DDS will check to see if the matching DataWriter is still alive.

DDS_Long

assertions_per_lease_duration

The number of assertions a DataWriter will send during a lease_duration period.

This field only applies to DataWriters using DDS_AUTOMATIC_LIVELINESS_QOS kind and it 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.

Setting a DataWriter’s kind of LIVELINESS specifies the mechanism that will be used to assert liveliness for the DataWriter. The DataWriter’s lease_duration then specifies the maximum period at which packets that indicate that the DataWriter is still alive are sent to matching DataReaders.

The various mechanisms are:

With the MANUAL_BY_[TOPIC,PARTICIPANT] settings, user application code can assert the liveliness of DataWriters either explicitly by calling the assert_liveliness() operation on the DataWriter (as well as the DomainParticipant for the MANUAL_BY_PARTICIPANT setting) or implicitly by calling write() on the DataWriter. If the application does not use either of the methods mentioned at least once every lease_duration, then the subscribing application may assume that the DataWriter is no longer alive. Sending data MANUAL_BY_TOPIC will cause an assert message to be sent between the DataWriter and its matched DataReaders.

Publishing applications will monitor their DataWriters to make sure that they are honoring their LIVELINESS QosPolicy by asserting their liveliness at least at the period set by the lease_duration. If Connext DDS finds that a DataWriter has failed to have its liveliness asserted by its lease_duration, an internal thread will modify the DataWriter’s LIVELINESS_LOST_STATUS and trigger its on_liveliness_lost() DataWriterListener callback if a listener exists, see Listeners.

Setting the DataReader’s kind of LIVELINESS requests a specific mechanism for the publishing application to maintain the liveliness of DataWriters. The subscribing application may want to know that the publishing application is explicitly asserting the liveliness of the matching DataWriter rather than inferring its liveliness through the liveliness of its DomainParticipant or its sibling DataWriters.

The DataReader’s 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 the DataWriter’s lease_duration has been violated.

When a matching DataWriter is determined to be dead (inactive), Connext DDS will modify the LIVELINESS_CHANGED_STATUS of each matching DataReader and trigger that DataReader’s on_liveliness_changed() DataReaderListener callback (if a listener exists).

Although you can set the LIVELINESS QosPolicy on Topics, its value can only be used to initialize the LIVELINESS QosPolicies of either a DataWriter or DataReader. It does not directly affect the operation of Connext DDS, see Setting Topic QosPolicies.

For more information on Liveliness, see Maintaining DataWriter Liveliness for kinds AUTOMATIC and MANUAL_BY_PARTICIPANT.

Example

You can use LIVELINESS QosPolicy during system integration to ensure that applications have been coded to meet design specifications. You can also use it during run time to detect when systems are performing outside of design specifications. Receiving applications can take appropriate actions in response to disconnected DataWriters.

The LIVELINESS QosPolicy can be used to manage fail-over when the OWNERSHIP QosPolicy is set to EXCLUSIVE. This implies that the DataReader will only receive data from the highest strength DataWriter that is alive (active). When that DataWriter’s liveliness expires, then Connext DDS will start delivering data from the next highest strength DataWriter that is still alive.

Properties

This QosPolicy cannot be modified after the Entity has been enabled.

The DataWriter and DataReader must use compatible settings for this QosPolicy. To be compatible, both of the following conditions must be true:

The DataWriter and DataReader must use one of the valid combinations shown in Table 50 .

DataWriter’s lease_duration <= DataReader’s lease_duration.

If this QosPolicy is found to be incompatible, the ON_OFFERED_INCOMPATIBLE_QOS and ON_REQUESTED_INCOMPATIBLE_QOS statuses will be modified and the corresponding Listeners called for the DataWriter and DataReader respectively.

Table 50 Valid Combinations of Liveliness ‘kind’

 

DataReader requests:

MANUAL_
BY_TOPIC

MANUAL_BY_PARTICIPANT

AUTO-
MATIC

DataWriter offers:

MANUAL_BY_TOPIC

4

4

4

MANUAL_BY_PARTICIPANT

incompatible

4

4

AUTOMATIC

incompatible

incompatible

4

Related QosPolicies

Applicable Entities

System Resource Considerations

An internal thread in Connext DDS will wake up periodically to check the liveliness of all the DataWriters. This happens both in the application that contains the DataWriters at the lease_duration set on the DataWriters as well as the applications that contain the DataReaders at the lease_duration set on the DataReaders. Therefore, as lease_duration becomes smaller, more CPU will be used to wake up threads and perform checks. A short lease_duration (or a high assertions_per_lease_duration) set on DataWriters may also use more network bandwidth because liveliness packets are being sent at a higher rate—this is especially true when LIVELINESS kind is set to AUTOMATIC.

© 2015 RTI