APIs related to Multi-channel DataWriters.
APIs related to Multi-channel DataWriters.
What is a Multi-channel DataWriter?
A Multi-channel dds::pub::DataWriter is a dds::pub::DataWriter that is configured to send data over multiple multicast addresses, according to some filtering criteria applied to the data.
To determine which multicast addresses will be used to send the data, the middleware evaluates a set of filters that are configured for the dds::pub::DataWriter. Each filter "guards" a channel (a set of multicast addresses). Each time a multi-channel dds::pub::DataWriter writes data, the filters are applied. If a filter evaluates to true, the data is sent over that filter's associated channel (set of multicast addresses). We refer to this type of filter as a Channel Guard filter.
Configuration on the Writer Side
To configure a multi-channel dds::pub::DataWriter, simply define a list of all its channels in the rti::core::policy::MultiChannel.
The rti::core::policy::MultiChannel is propagated along with discovery traffic. The value of this policy is available in dds::topic::PublicationBuiltinTopicData::locator_filter.
Configuration on the Reader Side
No special changes are required in a subscribing application to get data from a multichannel dds::pub::DataWriter. If you want the dds::sub::DataReader to subscribe to only a subset of the channels, use a dds::topic::ContentFilteredTopic.
For more information on Multi-channel DataWriters, refer to the User's Manual.
Reliability with Multi-Channel DataWriters
Reliable Delivery
Reliable delivery is only guaranteed when the dds::core::policy::Presentation::access_scope is set to dds::core::policy::PresentationAccessScopeKind_def::INSTANCE and the filters in rti::core::policy::MultiChannel are keyed-only based.
If any of the guard filters are based on non-key fields, RTI Connext only guarantees reception of the most recent data from the MultiChannel DataWriter.
Reliable Protocol Considerations
Reliability is maintained on a per-channel basis. Each channel has its own reliability channel send queue. The size of that queue is limited by dds::core::policy::ResourceLimits::max_samples and/or rti::core::policy::DataWriterResourceLimits::max_batches.
The protocol parameters described in rti::core::policy::DataWriterProtocol are applied per channel, with the following exceptions:
rti::core::RtpsReliableWriterProtocol::low_watermark and rti::core::RtpsReliableWriterProtocol::high_watermark: The low watermark and high watermark control the queue levels (in number of samples) that determine when to switch between regular and fast heartbeat rates. With MultiChannel DataWriters, high_watermark and low_watermark refer to the DataWriter's queue (not the reliability channel queue). Therefore, periodic heartbeating cannot be controlled on a per-channel basis.
Important: With MultiChannel DataWriters, low_watermark and high_watermark refer to application samples even if batching is enabled. This behavior differs from the one without MultiChannel DataWriters (where low_watermark and high_watermark refer to batches).
rti::core::RtpsReliableWriterProtocol::heartbeats_per_max_samples: This field defines the number of heartbeats per send queue. For MultiChannel DataWriters, the value is applied per channel. However, the send queue size that is used to calculate the a piggyback heartbeat rate is defined per DataWriter (see dds::core::policy::ResourceLimits::max_samples)
Important: With MultiChannel DataWriters, heartbeats_per_max_samples refers to samples even if batching is enabled. This behavior differs from the one without MultiChannels DataWriters (where heartbeats_per_max_samples refers to batches).
With batching and MultiChannel DataWriters, the size of the DataWriter's send queue should be configured using dds::core::policy::ResourceLimits::max_samples instead of max_batches
rti::core::policy::DataWriterResourceLimits::max_batches in order to take advantage of heartbeats_per_max_samples.