47.15 LIVELINESS QosPolicy

The LIVELINESS QosPolicy specifies how Connext determines whether a DataWriter is “alive.” A DataWriter’s liveliness is used in combination with the 47.17 OWNERSHIP QosPolicy to maintain ownership of an instance (note that the 47.7 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 47.27 DDS_LivelinessQosPolicy. For defaults and valid ranges, please refer to the API Reference HTML documentation.

Table 47.27 DDS_LivelinessQosPolicy

Type

Field Name

Description

DDS_LivelinessQosPolicyKind

kind

DDS_AUTOMATIC_LIVELINESS_QOS:

Connext 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

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 DataWriter is still alive.

The DataWriter lease_duration is the value that the DataReader uses to determine if a matching DataWriter is 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 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 15.8 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 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 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, see 18.1.3 Setting Topic QosPolicies.

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

47.15.1 Timing Considerations for MANUAL_BY_PARTICIPANT

As mentioned in 47.15.6 System Resource Considerations, a per-DomainParticipant internal Connext thread will wake up periodically to check the liveliness of the DataWriters. This same thread also checks if any of the MANUAL_BY_PARTICIPANT DataWriters within the DomainParticipant have asserted liveliness (by calling either the DomainParticipant's or the DataWriter's assert_liveliness() API): if that is the case, that thread is responsible for sending a liveliness assertion message to any matched remote DomainParticipants.

The period of this thread is half of the time given by the minimum lease_duration across all of the MANUAL_BY_PARTICIPANT DataWriters within the DomainParticipant. As a result, an application asserting MANUAL_BY_PARTICIPANT DataWriters' liveliness at a period equal to or higher than half of the minimum configured lease_duration may run into local and/or remote DataWriter lost events.

For example, for a minimum lease_duration across all DataWriters of 2 seconds and an application assertion period (the time between calls to assert_liveliness()) of 1 second, the maximum time between two liveliness assertions will be given by:

"maximum time between two liveliness assertions" ~= ("minimum lease_duration across manual_by_participant datawriters" / 2) + "application assertion period"

which results in:

"maximum time between two liveliness assertions" ~= (2 / 2) second + 1 second = 2 seconds

This configuration results in potential (local and remote) liveliness losses since the lease_duration is close to the maximum time between two liveliness assertions (in fact, the situation will be a bit worse since this configuration has not accounted for network delay/jittering delivering liveliness assertion messages).

Therefore, to avoid unexpected liveliness losses, the user application should make sure that DataWriters' liveliness is asserted at a period that is shorter than half of the minimum lease duration. For additional information and diagrams, see 25.1.2 Maintaining DataWriter Liveliness for kinds AUTOMATIC and MANUAL_BY_PARTICIPANT.

47.15.2 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 47.17 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 will start delivering data from the next highest strength DataWriter that is still alive.

47.15.3 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:

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 47.28 Valid Combinations of Liveliness ‘kind’

 

DataReader requests:

MANUAL_BY_TOPIC

MANUAL_BY_PARTICIPANT

AUTOMATIC

DataWriter offers:

MANUAL_BY_TOPIC

compatible

compatible

compatible

MANUAL_BY_PARTICIPANT

incompatible

compatible

compatible

AUTOMATIC

incompatible

incompatible

compatible

47.15.4 Related QosPolicies

47.15.5 Applicable Entities

47.15.6 System Resource Considerations

An internal thread in Connext 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.