APIs related to Multi-channel DataWriters. More...
APIs related to Multi-channel DataWriters.
What is a Multi-channel DataWriter?
A Multi-channel DDSDataWriter is a DDSDataWriter 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 DDSDataWriter. Each filter "guards" a channel (a set of multicast addresses). Each time a multi-channel DDSDataWriter 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 DDSDataWriter, simply define a list of all its channels in the DDS_MultiChannelQosPolicy.
The DDS_MultiChannelQosPolicy is propagated along with discovery traffic. The value of this policy is available in DDS_PublicationBuiltinTopicData::locator_filter.
Configuration on the Reader Side
No special changes are required in a subscribing application to get data from a multichannel DDSDataWriter. If you want the DDSDataReader to subscribe to only a subset of the channels, use a DDSContentFilteredTopic.
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_PresentationQosPolicy::access_scope is set to DDS_INSTANCE_PRESENTATION_QOS and the filters in DDS_MultiChannelQosPolicy 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_ResourceLimitsQosPolicy::max_samples and/or DDS_DataWriterResourceLimitsQosPolicy::max_batches.
The protocol parameters described in DDS_DataWriterProtocolQosPolicy are applied per channel, with the following exceptions:
DDS_RtpsReliableWriterProtocol_t::low_watermark and DDS_RtpsReliableWriterProtocol_t::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).
DDS_RtpsReliableWriterProtocol_t::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_ResourceLimitsQosPolicy::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_ResourceLimitsQosPolicy::max_samples instead of max_batches DDS_DataWriterResourceLimitsQosPolicy::max_batches in order to take advantage of heartbeats_per_max_samples.