RTI Connext C API  Version 6.1.2

APIs related to Multi-channel DataWriters. More...

APIs related to Multi-channel DataWriters.

What is a Multi-channel DataWriter?

A Multi-channel DDS_DataWriter is a DDS_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_DataWriter. Each filter "guards" a channel (a set of multicast addresses). Each time a multi-channel DDS_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.

DDSMultichannel1.jpg
Multi-channel data flow
DDSMultichannel2.jpg
Multi-channel evaluation

Configuration on the Writer Side

To configure a multi-channel DDS_DataWriter, 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 DDS_DataWriter. If you want the DDS_DataReader to subscribe to only a subset of the channels, use a DDS_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_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.