rti::core::policy::Availability Class Reference

<<extension>> Configures data availability in the context of Collaborative DataWriters and Required Subscriptions More...

#include <rti/core/policy/CorePolicy.hpp>

Public Member Functions
	Availability ()
	Creates the default policy. More...
	Availability (bool the_enable_required_subscriptions, const dds::core::Duration &the_data_waiting_time, const dds::core::Duration &the_endpoint_waiting_time, const rti::core::EndpointGroupSeq &the_required_enpoint_groups)
	Creates a policy with all the paramters. More...
Availability &	enable_required_subscriptions (bool the_enable_required_subscriptions)
	Enables support for required subscriptions in a dds::pub::DataWriter. More...
bool	enable_required_subscriptions () const
	Getter (see setter with the same name) More...
Availability &	max_data_availability_waiting_time (const dds::core::Duration &the_data_waiting_time)
	Defines how much time to wait before delivering a sample to the application without having received some of the previous samples. More...
dds::core::Duration	max_data_availability_waiting_time () const
	Getter (see setter with the same name) More...
Availability &	max_endpoint_availability_waiting_time (const dds::core::Duration &the_endpoint_waiting_time)
	Defines how much time to wait to discover DataWriters providing samples for the same data source (virtual GUID). More...
dds::core::Duration	max_endpoint_availability_waiting_time () const
	Getter (see setter with the same name) More...
Availability &	required_matched_endpoint_groups (const rti::core::EndpointGroupSeq &the_required_enpoint_groups)
	A sequence of endpoint groups. More...
rti::core::EndpointGroupSeq	required_matched_endpoint_groups () const
	Getter (see setter with the same name) More...

Detailed Description

<<extension>> Configures data availability in the context of Collaborative DataWriters and Required Subscriptions

Entity:

dds::sub::DataReader, dds::pub::DataWriter

Properties:

RxO = NO
Changeable = YES (only on a dds::pub::DataWriter except for the member rti::core::policy::Availability::enable_required_subscriptions)

Usage

This QoS policy is used in the context of two features:

• Collaborative DataWriters
• Required Subscriptions

Collaborative DataWriters

The Collaborative DataWriters feature allows having multiple DataWriters publishing samples from a common logical data source. The DataReaders will combine the samples coming from the DataWriters in order to reconstruct the correct order at the source.

This QoS policy allows you to configure the ordering and combination process in the DataReader and can be used to support two different use cases:

• Ordered delivery of samples in high-availability scenarios One example of this is RTI Persistence Service. When a late-joining DataReader configured with dds::core::policy::Durability set to dds::core::policy::DurabilityKind::PERSISTENT or dds::core::policy::DurabilityKind::TRANSIENT joins a DDS domain, it will start receiving historical samples from multiple DataWriters. For example, if the original DataWriter is still alive, the newly created DataReader will receive samples from the original DataWriter and one or more RTI Persistence Service DataWriters (PRSTDataWriters). This policy can be used to configure the sample ordering process on the DataReader.

• Ordered delivery of samples in load-balanced scenarios Multiple instances of the same application can work together to process and deliver samples. When the samples arrive through different data-paths out of order, the DataReader will be able to reconstruct the order at the destination. An example of this is when multiple instances of RTI Persistence Service are used to persist the data. Persisting data to a database on disk can be a bottleneck for throughput. You can improve scalability and performance by dividing the workload across different instances of RTI Persistence Service that use different databases. For example, samples larger than 10 are persisted by Persistence Service 1, samples less than or equal to 10 are persisted by Persistence Service 2.

• Ordered delivery of samples with Group Ordered Access This policy can also be used to configure the sample ordering process when the Subscriber is configured with dds::core::policy::Presentation access_scope set to dds::core::policy::PresentationAccessScopeKind_def::GROUP. In this case, the Subscriber must deliver in order the samples published by a group of DataWriters that belong to the same Publisher and have access_scope set to dds::core::policy::PresentationAccessScopeKind_def::GROUP.

Each sample published in a DDS domain for a given logical data source is uniquely identified by a pair (virtual GUID, virtual sequence number). Samples from the same data source (same virtual GUID) can be published by different DataWriters. A DataReader will deliver a sample (VGUIDn, VSNm) to the application if one of the following conditions is satisfied:

• (VGUIDn, VSNm-1) has already been delivered to the application.
• All the known DataWriters publishing VGUIDn have announced that they do not have (VGUIDn, VSNm-1).
• None of the known DataWriters publishing GUIDn have announced potential availability of (VGUIDn, VSNm-1) and both timeouts in this QoS policy have expired.

A DataWriter announces potential availability of samples by using virtual heartbeats (HBs).

When dds::core::policy::Presentation::access_scope is set to dds::core::policy::PresentationAccessScopeKind_def::TOPIC or dds::core::policy::PresentationAccessScopeKind_def::INSTANCE, the virtual HB contains information about the samples contained in the dds::pub::DataWriter history.

When dds::core::policy::Presentation::access_scope is set to dds::core::policy::PresentationAccessScopeKind_def::GROUP, the virtual HB contains information about all DataWriters in the dds::pub::Publisher.

The frequency at which virtual HBs are sent is controlled by the protocol parameters rti::core::RtpsReliableWriterProtocol::virtual_heartbeat_period and rti::core::RtpsReliableWriterProtocol::samples_per_virtual_heartbeat.

Required Subscriptions

In the context of Required Subscriptions, this QoS policy can be used to configure a set of Required Subscriptions on a dds::pub::DataWriter.

Required subscriptions are preconfigured, named subscriptions that may leave and subsequently rejoin the network from time to time, at the same or different physical locations. Any time a required subscription is disconnected, any samples that would have been delivered to it are stored for delivery if and when the subscription rejoins the network.

Consistency

For a DataWriter, the setting of AVAILABILITY must be set consistenly with that of the RELIABILITY and DURABILITY.

If rti::core::policy::Availability::enable_required_subscriptions is set to true, dds::core::policy::Reliability::kind must be set to dds::core::policy::ReliabilityKind_def::RELIABLE, dds::core::policy::Durability must be set to a value different than dds::core::policy::DurabilityKind::VOLATILE, and dds::core::policy::Durability::writer_depth must be set to either rti::core::policy::auto_writer_depth() or dds::core::LENGTH_UNLIMITED.

Constructor & Destructor Documentation

Availability() [1/2]

rti::core::policy::Availability::Availability ( )

inline

Creates the default policy.

Availability() [2/2]

rti::core::policy::Availability::Availability	(	bool	the_enable_required_subscriptions,
		const dds::core::Duration &	the_data_waiting_time,
		const dds::core::Duration &	the_endpoint_waiting_time,
		const rti::core::EndpointGroupSeq &	the_required_enpoint_groups
	)

Creates a policy with all the paramters.

Member Function Documentation

enable_required_subscriptions() [1/2]

Availability& rti::core::policy::Availability::enable_required_subscriptions

(

bool

the_enable_required_subscriptions

)

Enables support for required subscriptions in a dds::pub::DataWriter.

[default] false

enable_required_subscriptions() [2/2]

bool rti::core::policy::Availability::enable_required_subscriptions

(

)

const

Getter (see setter with the same name)

max_data_availability_waiting_time() [1/2]

Availability& rti::core::policy::Availability::max_data_availability_waiting_time

(

const dds::core::Duration &

the_data_waiting_time

)

Defines how much time to wait before delivering a sample to the application without having received some of the previous samples.

Collaborative DataWriters

A sample identified by (VGUIDn, VSNm) will be delivered to the application if this timeout expires for the sample and the following two conditions are satisfied:

• None of the known DataWriters publishing VGUIDn have announced potential availability of (VGUIDn, VSNm-1).
• The DataWriters for all the endpoint groups specified in required_matched_endpoint_groups have been discovered or max_endpoint_availability_waiting_time has expired.

Required Subscriptions

This field is not applicable to Required Subscriptions.

[default] dds::core::Duration::automatic() (dds::core::Duration::infinite() for dds::core::policy::PresentationAccessScopeKind_def::GROUP. Otherwise, 0 seconds)

[range] [0, dds::core::Duration::infinite()], dds::core::Duration::automatic()

max_data_availability_waiting_time() [2/2]

dds::core::Duration rti::core::policy::Availability::max_data_availability_waiting_time

(

)

const

Getter (see setter with the same name)

max_endpoint_availability_waiting_time() [1/2]

Availability& rti::core::policy::Availability::max_endpoint_availability_waiting_time

(

const dds::core::Duration &

the_endpoint_waiting_time

)

Defines how much time to wait to discover DataWriters providing samples for the same data source (virtual GUID).

Collaborative DataWriters

The set of endpoint groups that are required to provide samples for a data source can be configured using required_matched_endpoint_groups.

A non-consecutive sample identified by (VGUIDn, VSNm) cannot be delivered to the application unless DataWriters for all the endpoint groups in required_matched_endpoint_groups are discovered or this timeout expires.

Required Subscriptions

This field is not applicable to Required Subscriptions.

[default] dds::core::Duration::automatic() (dds::core::Duration::infinite() for dds::core::policy::PresentationAccessScopeKind_def::GROUP. Otherwise, 0 seconds)

[range] [0, dds::core::Duration::infinite()], dds::core::Duration::automatic()

max_endpoint_availability_waiting_time() [2/2]

dds::core::Duration rti::core::policy::Availability::max_endpoint_availability_waiting_time

(

)

const

Getter (see setter with the same name)

required_matched_endpoint_groups() [1/2]

Availability& rti::core::policy::Availability::required_matched_endpoint_groups

(

const rti::core::EndpointGroupSeq &

the_required_enpoint_groups

)

A sequence of endpoint groups.

Collaborative DataWriters

In the context of Collaborative DataWriters, it specifies the set of endpoint groups that are expected to provide samples for the same data source.

The quorum count in a group represents the number of DataWriters that must be discovered for that group before the DataReader is allowed to provide non consecutive samples to the application.

A DataWriter becomes a member of an endpoint group by configuring the role_name in rti::core::policy::EntityName.

Required Subscriptions

In the context of Required Subscriptions, it specifies the set of Required Subscriptions on a dds::pub::DataWriter.

Each Required Subscription is specified by a name and a quorum count.

The quorum count represents the number of DataReaders that have to acknowledge the sample before it can be considered fully acknowledged for that Required Subscription.

A DataReader is associated with a Required Subscription by configuring the role_name in rti::core::policy::EntityName.

[default] Empty sequence

required_matched_endpoint_groups() [2/2]

rti::core::EndpointGroupSeq rti::core::policy::Availability::required_matched_endpoint_groups

(

)

const

Getter (see setter with the same name)