RTI Connext Micro C API  Version 2.4.14.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
DDS_LivelinessQosPolicy Struct Reference

<<cert>> Determines the mechanism and parameters used by the application to determine whether a DDS_Entity is alive. More...

Data Fields

DDS_LivelinessQosPolicyKind kind
 The kind of liveliness desired.
struct DDS_Duration_t lease_duration
 The duration within which a DDS_Entity must be asserted, or else it is assumed to be not alive.

Detailed Description

<<cert>> Determines the mechanism and parameters used by the application to determine whether a DDS_Entity is alive.

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

The liveliness status of a DDS_Entity 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_Entity is no longer alive.

A DDS_DataWriter commits to signalling its liveliness using the stated means at intervals not to exceed the lease_duration. That is, a failure by the DDS_DataWriter to assert liveliness within its offered lease_duration will result in a DDS_LIVELINESS_LOST_STATUS event.

A DDS_DataReader will match a DDS_DataWriter if the DDS_DataReader's requested lease_duration is equal to or larger than the lease_duration offered by the DDS_DataWriter and the offered kind is equal to or better than the requested kind. In addition, a DDS_DataReader uses its own lease_duration as the check period to check if a DDS_DataWriter was active or not. This means that a DDS_DataWriter may be inactive for up to, but not including, twice the DDS_DataReader's lease_duration before being detected as inactive by the DDS_DataReader. It does not matter when the DDS_DataWriter was active, or how many times the DDS_DataWriter was active within the last DDS_DataReader's lease_duration to be considered inactive.

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

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_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

This policy controls the mechanism and parameters used by RTI Connext Micro to ensure that particular entities 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_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 Micro 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_MANUAL_BY_PARTICIPANT_LIVELINESS_QOS, DDS_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.

Changes in LIVELINESS must be detected by the Service with a time-granularity greater or equal to the lease_duration. This ensures that the value of the DDS_LivelinessChangedStatus is updated at least once during each lease_duration and the related Listeners 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:


Field Documentation

DDS_LivelinessQosPolicyKind DDS_LivelinessQosPolicy::kind

The kind of liveliness desired.

[default] DDS_AUTOMATIC_LIVELINESS_QOS

struct DDS_Duration_t DDS_LivelinessQosPolicy::lease_duration

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

[default] DDS_DURATION_INFINITE

[range] [0,1 year] or DDS_DURATION_INFINITE


RTI Connext Micro C API Version 2.4.14.1 Copyright © Thu Nov 2 2023 Real-Time Innovations, Inc