19.3.4 Topic Filters
A QoS profile may contain several writer, reader and topic QoSs. Connext DDS will select a QoS based on the evaluation of a filter expression on the topic name. The filter expression is specified as an attribute in the XML QoS definition. For example:
<qos_profile name="StrictReliableCommunicationProfile"> <datawriter_qos topic_filter="A*"> <history> <kind>KEEP_ALL_HISTORY_QOS</kind> </history> <reliability> <kind>RELIABLE_RELIABILITY_QOS</kind> </reliability> </datawriter_qos> <datawriter_qos topic_filter="B*"> <history> <kind>KEEP_ALL_HISTORY_QOS</kind> </history> <reliability> <kind>RELIABLE_RELIABILITY_QOS</kind> </reliability> <resource_limits> <max_samples>128</max_samples> <max_samples_per_instance>128 </max_samples_per_instance> <initial_samples>128</initial_samples> <max_instances>1</max_instances> <initial_instances>1</initial_instances> </resource_limits> </datawriter_qos> ... </qos_profile>
If topic_filter is not specified in a QoS, Connext DDS will assume the filter '*'. The QoSs with an explicit topic_filter attribute definition will be evaluated in order; they have precedence over a QoS without a topic_filter expression.
The topic_filter attribute is only used with the following APIs:
DomainParticipantFactory:
- get_<entity>_qos_from_profile_w_topic_name() (where <entity> may be topic, datareader, or datareader; see 9.2.5 Getting QoS Values from a QoS Profile)
DomainParticipant:
- create_datawriter_with_profile() (see 7.3.1 Creating DataWriters)
- create_datareader_with_profile() (see 8.3.1 Creating DataReaders
- create_topic_with_profile() (see 5.1.1 Creating Topics)
Publisher:
- create_datawriter_with_profile() (see 7.3.1 Creating DataWriters)
Subscriber:
- create_datareader_with_profile() (see 8.3.1 Creating DataReaders)
Topic:
- set_qos_with_profile() (see 5.1.3 Setting Topic QosPolicies)
DataWriter:
- set_qos_with_profile() (see 7.2.4.3 Changing QoS Settings After the Publisher Has Been Created)
DataReader:
- set_qos_with_profile() (see 8.3.9 Setting DataReader QosPolicies)
Note: in the Modern C++ API, use dds::core::QosProvider::<entity>_qos_w_topic_name() to obtain the Qos associated with a topic. For example:
auto reader_qos = qos_provider.extensions().datareader_qos_w_topic_name("Example Topic");dds::sub::DataReader<Foo> reader(subscriber, topic, reader_qos);
Other APIs will ignore QoSs with a topic_filter value different than "*". A QoS Profile with QoSs using topic_filter can also inherit from other QoS Profiles. In this case, inheritance will consider the value of the topic_filter expression.
Example 1:
<qos_library name=”Library”>
<qos_profile name="BaseProfile">
<datawriter_qos>
...
</datawriter_qos>
<datawriter_qos topic_filter="T1*">
...
</datawriter_qos>
<datawriter_qos topic_filter="T2*">
...
</datawriter_qos>
</qos_profile>
<qos_profile name="DerivedProfile" base_name="BaseProfile">
<datawriter_qos topic_filter="T11">
...
</datawriter_qos>
<datawriter_qos topic_filter="T21">
...
</datawriter_qos>
<datawriter_qos topic_filter="T31">
...
</datawriter_qos>
</qos_profile>
</qos_library>
The datawriter_qos with topic_filter T11 in DerivedProfile will inherit its values from the datawriter_qos with topic_filter T1* in BaseProfile. The datawriter_qos with topic_filter T21 in DerivedProfile will inherit its values from the datawriter_qos with topic_filter T2* in BaseProfile. The datawriter_qos with topic_filter T31 in DerivedProfile will inherit its values from the datawriter_qos without topic_filter in BaseProfile.
Example 2:
<qos_library name=”Library”>
<qos_profile name="BaseProfile">
<datawriter_qos topic_filter="T1*">
...
</datawriter_qos>
<datawriter_qos name="T2DataWriterQoS" topic_filter="T2*">
...
</datawriter_qos>
</qos_profile>
<qos_profile name="DerivedProfile" base_name="BaseProfile">
<datawriter_qos topic_filter="T11"
base_name="BaseProfile::T2DataWriterQoS">
...
</datawriter_qos>
<datawriter_qos topic_filter="T21">
...
</datawriter_qos>
</qos_profile>
</qos_library>
Although the topic_filter expressions do not match, the datawriter_qos with topic_filter T11 in DerivedProfile will inherit its values from the datawriter_qos with topic_filter T2* in BaseProfile. topic_filter is not used with inheritance from QoS to QoS. The datawriter_qos with topic_filter T21 in DerivedProfile will inherit its values from the datawriter_qos with topic_filter T2* in BaseProfile.
Example 3:
<qos_library name=”Library”> <datawriter_qos name="BaseQos" topic_filter="T1"> ... </datawriter_qos> <datawriter_qos name="DerivedQos" base_name="BaseQos" topic_filter="T2"> ... </datawriter_qos> </qos_library>
In the case of a single QoS profile, although the topic_filter expressions do not match, the datawriter_qos named DerivedQos with topic_filter T2 will inherit its values from the datawriter_qos named BaseQos with topic_filter T1.
Important Note About Topic Filters
Use the topic_filter attribute with caution. In most cases, governance of QoS is improved by using discrete, named QoS profiles with no more than one of each kind of entity QoS section (datareader_qos, datawriter_qos, etc.) in each profile. If the topic_filter attribute contains a typographical error or omission, it is possible for a topic not to match the intended filter expression. This can result in, for example, the entity being silently assigned the default QoS. The topic_filter attribute may be preferred in cases where wildcards are used extensively to reduce duplication in the XML. In these cases, the resulting QoS of each entity should be independently and empirically confirmed. Tools that can help confirm an entity’s QoS are RTI Monitor and (as described in 19.3.3.5 Viewing Resolved QoS Values) the rtixmloutpututility.
© 2021 RTI