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 DDS_LivelinessQosPolicy. For defaults and valid ranges, please refer to the API Reference HTML documentation.
Type |
Field Name |
Description |
DDS_LivelinessQosPolicyKind |
kind |
DDS_AUTOMATIC_LIVELINESS_QOS: DDS_MANUAL_BY_PARTICIPANT_LIVELINESS_QOS: DDS_MANUAL_BY_TOPIC_LIVELINESS_QOS: |
DDS_Duration_t |
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. A DataReader will consider a DataWriter not alive if the DataWriter does not assert its liveliness within the DataWriter's lease_duration, not the DataReader's lease_duration. |
|
DDS_Long |
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:
The DomainParticipant is responsible for automatically sending packets to indicate that the DataWriter is alive; this will be done at the rate determined by the assertions_per_lease_duration and lease_duration values. This setting is appropriate when the primary failure mode is that the publishing application itself dies. It does not cover the case in which the application is still alive but in an erroneous state–allowing the DomainParticipant to continue to assert liveliness for the DataWriter but preventing threads from calling write() on the DataWriter.
As long as the internal threads spawned by Connext DDS for a DomainParticipant are running, then the liveliness of the DataWriter will be asserted regardless of the state of the rest of the application.
This setting is certainly the most convenient, if the least accurate, method of asserting liveliness for a DataWriter.
Connext DDS will assume that as long as the user application has asserted the liveliness of at least one DataWriter belonging to the same DomainParticipant or the liveliness of the DomainParticipant itself, then this DataWriter is also alive.
This setting allows the user code to control the assertion of liveliness for an entire group of DataWriters with a single operation on any of the DataWriters or their DomainParticipant. Its a good balance between control and convenience.
The DataWriter is considered alive only if the user application has explicitly called operations that assert the liveliness for that particular DataWriter.
This setting forces the user application to assert the liveliness for a DataWriter which gives the user application great control over when other applications can consider the DataWriter to be inactive, but at the cost of convenience.
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.
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.
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 Valid Combinations of Liveliness ‘kind’.
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.
|
DataReader requests: |
|||
MANUAL_BY_TOPIC |
MANUAL_BY_PARTICIPANT |
AUTOMATIC |
||
DataWriter offers: |
MANUAL_BY_TOPIC |
4 |
4 |
4 |
MANUAL_BY_PARTICIPANT |
incompatible |
4 |
4 |
|
AUTOMATIC |
incompatible |
incompatible |
4 |
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.
© 2017 RTI