Determines the mechanism and parameters used by the application to determine whether a DDSEntity is alive. More...

#include <dds_c_infrastructure.h>

Public Attributes
DDS_LivelinessQosPolicyKind	kind
	The kind of liveliness desired.

struct DDS_Duration_t	lease_duration
	The duration within which a DDSEntity must be asserted, or else it is assumed to be not alive.

Detailed Description

Determines the mechanism and parameters used by the application to determine whether a DDSEntity is alive.

Liveliness must be asserted at least once every lease_duration otherwise RTI Connext DDS Micro will assume the corresponding DDSEntity is no longer alive.

The liveliness status of a DDSEntity is used to maintain instance ownership in combination with the setting of the OWNERSHIP policy. The application also receives notification via DDSListener when an DDSEntity is no longer alive.

A DDSDataReader requests that writers maintain liveliness using the requested DDS_LivelinessQosPolicy::kind. Liveliness loss must be detected within the lease_duration.

A DDSDataWriter commits to signalling its liveliness using the requested DDS_LivelinessQosPolicy::kind at intervals that do not exceed the lease_duration. A failure by the DDSDataWriter to assert liveliness within its offered lease_duration will result in a DDS_LIVELINESS_LOST_STATUS event.

If the DDSDataReader's requested lease_duration is greater than or equal to the lease_duration offered by the DDSDataWriter and the offered kind is equal to or better than the requested kind, they will match. The DDSDataReader uses its own lease_duration as the check period to determine if a DDSDataWriter is active. A DDSDataWriter may be undetected as inactive for up to twice the DDSDataReader's lease_duration. The frequency and timing of prior activity do not affect whether the writer is considered inactive.

For example: If a DDSDataReader must detect that a DDSDataWriter was inactive within at most 100ms, both the DDSDataWriter and DDSDataReader must specify a lease_duration of 50ms.

Listeners notify a DDSDataReader when liveliness is lost and notify a DDSDataWriter when it violates the liveliness contract. The on_liveliness_lost() callback is called once, the first time the lease_duration is exceeded.

Applications can use the liveliness policy to verify that systems meet design specifications during integration and at runtime. Applications can detect when systems operate outside specifications and respond appropriately to disconnected DDSDataWriter entities.

Entity:: DDSTopic, DDSDataReader, DDSDataWriter

Status:: DDS_LIVELINESS_LOST_STATUS, DDS_LivelinessLostStatus;
DDS_LIVELINESS_CHANGED_STATUS, DDS_LivelinessChangedStatus;
DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS, DDS_OFFERED_INCOMPATIBLE_QOS_STATUS

Properties:: RxO = YES
Changeable = NO

Usage

The liveliness policy controls the mechanism and parameters used by RTI Connext DDS Micro to ensure that particular entities on the network are still alive. The liveliness policy 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 customization for different application requirements in terms of the kinds of failures that will be detected by the liveliness mechanism.

The DDS_AUTOMATIC_LIVELINESS_QOS liveliness setting is most appropriate for applications that only need to detect process-level failures, not application-logic failures within a process. RTI Connext DDS Micro takes responsibility for renewing the leases at the required rates and thus, as long as the local process where a DDSDomainParticipant is running and the link connecting it to remote participants remain connected, RTI Connext DDS Micro considers the entities within the DDSDomainParticipant alive. This requires the lowest overhead.

The manual settings include both DDS_MANUAL_BY_PARTICIPANT_LIVELINESS_QOS and DDS_MANUAL_BY_TOPIC_LIVELINESS_QOS. These require the application on the publishing side to periodically assert liveliness before the lease expires to indicate the corresponding DDSEntity is still alive. The action can be explicit by calling DDSDataWriter::assert_liveliness, or implicit by writing data.

The two possible manual settings control the granularity at which the application must assert liveliness.

The setting DDS_MANUAL_BY_PARTICIPANT_LIVELINESS_QOS requires only that one DDSEntity within a participant is asserted to be alive to infer that all other DDSEntity objects within the same DDSDomainParticipant are also alive.

The setting DDS_MANUAL_BY_TOPIC_LIVELINESS_QOS requires that at least one instance within the DDSDataWriter is asserted.

The service must detect changes in LIVELINESS with time granularity greater than or equal to the lease_duration. This ensures that RTI Connext DDS Micro updates DDS_LivelinessChangedStatus at least once per lease_duration and notifies Listeners within a lease_duration of the configuration change.

Compatibility

A DDSDataWriter's offered liveliness policy matches a DDSDataReader's requested liveliness policy if and only if the following conditions are true:

the inequality offered kind >= requested kind evaluates to true. For this comparison, DDS_LivelinessQosPolicyKind values are ordered as follows: DDS_AUTOMATIC_LIVELINESS_QOS < DDS_MANUAL_BY_PARTICIPANT_LIVELINESS_QOS < DDS_MANUAL_BY_TOPIC_LIVELINESS_QOS.
the inequality offered lease_duration <= requested lease_duration evaluates to DDS_BOOLEAN_TRUE.

Member Data Documentation

◆ kind

DDS_LivelinessQosPolicyKind DDS_LivelinessQosPolicy::kind

The kind of liveliness desired.

[default] DDS_AUTOMATIC_LIVELINESS_QOS

◆ lease_duration

struct DDS_Duration_t DDS_LivelinessQosPolicy::lease_duration

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

[default] DDS_DURATION_INFINITE