DDS_LivelinessQosPolicy Struct Reference

Specifies and configures the mechanism that allows DDSDataReader entities to detect when DDSDataWriter entities become disconnected or "dead.". More...

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.
DDS_Long	assertions_per_lease_duration
	The number of assertions a DDSDataWriter will send during a DDS_LivelinessQosPolicy::lease_duration.

Detailed Description

Specifies and configures the mechanism that allows DDSDataReader entities to detect when DDSDataWriter entities become disconnected or "dead.".

Liveliness must be asserted at least once every DDS_LivelinessQosPolicy::lease_duration otherwise RTI Connext will assume the corresponding DDSEntity or 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 is also informed via DDSListener when an DDSEntity is no longer alive.

A DDSDataReader requests that liveliness of writers is maintained by the requested means and loss of liveliness is detected with delay not to exceed the DDS_LivelinessQosPolicy::lease_duration.

A DDSDataWriter commits to signalling its liveliness using the stated means at intervals not to exceed the DDS_LivelinessQosPolicy::lease_duration. The rate at which the DDSDataWriter will signal its liveliness is defined by DDS_LivelinessQosPolicy::assertions_per_lease_duration.

Listeners are used to notify a DDSDataReader of loss of liveliness and DDSDataWriter of violations to the liveliness contract. The on_liveliness_lost() callback is only called once, after the first time the DDS_LivelinessQosPolicy::lease_duration is exceeded (when the DDSDataWriter 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:

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 = UNTIL ENABLE

Usage

This policy controls the mechanism and parameters used by RTI Connext 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 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 remains connected, the entities within the DDSDomainParticipant 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 DDSEntity is still alive. The action can be explicit by calling the DDSDataWriter::assert_liveliness operation or implicit by writing some 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 deduce 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.

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

• the inequality offered kind >= requested kind evaluates to 'TRUE'. For the purposes of this inequality, the values of DDS_LivelinessQosPolicyKind kind are considered ordered such that: 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.

See Also

Relationship between registration, liveliness and ownership The need for registering/unregistering instances stems from two use cases:

• Ownership resolution on redundant systems

• Detection of loss in topological connectivity

These two use cases also illustrate the semantic differences between the ::FooDataWriter::unregister_instance and ::FooDataWriter::dispose. BROKEN_SECTIONS

Member Data 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 DDSEntity must be asserted, or else it is assumed to be not alive.

[default] DDS_DURATION_INFINITE

[range] [0,1 year] or DDS_DURATION_INFINITE

DDS_Long DDS_LivelinessQosPolicy::assertions_per_lease_duration

The number of assertions a DDSDataWriter will send during a DDS_LivelinessQosPolicy::lease_duration.

This field only applies to a DDSDataWriter and 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.

[default] 3

[range] [2, 100 million]