PARTITION QosPolicy

The PARTITION QoS provides another way to control which DataWriters will match—and thus communicate with—which DataReaders. It can be used to prevent DataWriters and DataReaders that would have otherwise matched with the same Topic and compatible QosPolicies from talking to each other. Much in the same way that only applications within the same DDS domain will communicate with each other, only DataWriters and DataReaders that belong to the same partition can talk to each other.

The PARTITION QoS applies to Publishers and Subscribers, therefore the DataWriters and DataReaders belong to the partitions as set on the Publishers and Subscribers that created them. The mechanism implementing the PARTITION QoS is relatively lightweight, and membership in a partition can be dynamically changed. Unlike the creation and destruction of DomainParticipants, there is no spawning and killing of threads or allocation and deallocation of memory when Publishers and Subscribers add or remove themselves from partitions.

The PARTITION QoS consists of a set of partition names that identify the partitions of which the Entity is a member. These names are simply strings, and DataWriters and DataReaders are considered to be in the same partition if they have at least one partition name in common in the PARTITION QoS set on their Publishers or Subscribers. By default, Publishers and Subscribers belong to a single partition whose name is the empty string, ““.

Conceptually each partition name can be thought of as defining a “visibility plane” within the DDS domain. DataWriters will make their data available on all the visibility planes that correspond to its Publisher’s partition names, and the DataReaders will see the data that is placed on any of the visibility planes that correspond to its Subscriber’s partition names.

Figure 28 illustrates the concept of PARTITION QoS. In this figure, all DataWriters and DataReaders belong to the same DDS domain and refer to the same Topic. DataWriter1 is configured to belong to three partitions: partition_A, partition_B, and partition_C. DataWriter2 belongs to partition_C and partition_D.

Figure 28 Controlling Visibility of Data with the PARTITION QoS

Similarly, DataReader1 is configured to belong to partition_A and partition_B, and DataReader2 belongs only to partition_C. Given this topology, the data written by DataWriter1 is visible in partitions A, B, and C. The oval tagged with the number “1” represents one DDS data sample written by DataWriter1.

Similarly, the data written by DataWriter2 is visible in partitions C and D. The oval tagged with the number “2” represents one DDS data sample written by DataWriter2.

The result is that the data written by DataWriter1 will be received by both DataReader1 and DataReader2, but the data written by DataWriter2 will only be visible by DataReader2.

Publishers and Subscribers always belong to a partition. By default, Publishers and Subscribers belong to a single partition whose name is the empty string, ““. If you set the PARTITION QoS to be an empty set, Connext DDS will assign the Publisher or Subscriber to the default partition, ““. Thus, for the example above, without using the PARTITION QoS, DataReaders 1 and 2 would have received all DDS data DDS samples written by DataWriters 1 and 2.

Rules for PARTITION Matching

On the Publisher side, the PARTITION QosPolicy associates a set of strings (partition names) with the Publisher. On the Subscriber side, the application also uses the PARTITION QoS to associate partition names with the Subscriber.

Taking into account the PARTITION QoS, a DataWriter will communicate with a DataReader if and only if the following conditions apply:

1. The DataWriter and DataReader belong to the same DDS domain. That is, their respective DomainParticipants are bound to the same DDS domain ID (see Creating a DomainParticipant).
2. The DataWriter and DataReader have matching Topics. That is, each is associated with a Topic with the same topic_name and data type.
3. The QoS offered by the DataWriter is compatible with the QoS requested by the DataReader.
4. The application has not used the ignore_participant(), ignore_datareader(), or ignore_datawriter() APIs to prevent the association (see Restricting Communication—Ignoring Entities).
5. The Publisher to which the DataWriter belongs and the Subscriber to which the DataReader belongs must have at least one matching partition name.

The last condition reflects the visibility of the data introduced by the PARTITION QoS. Matching partition names is done by string comparison, thus partition names are case sensitive.

Note: Failure to match partitions is not considered an incompatible QoS and does not trigger any listeners or change any status conditions.

Pattern Matching for PARTITION Names

You may also add strings that are regular expressions1As defined by the POSIX fnmatch API (1003.2-1992 section B.6). to the PARTITION QosPolicy. A regular expression does not define a set of partitions to which the Publisher or Subscriber belongs, as much as it is used in the partition matching process to see if a remote entity has a partition name that would be matched with the regular expression. That is, the regular expressions in the PARTITION QoS of a Publisher are never matched against those found in the PARTITION QoS of a Subscriber. Regular expressions are always matched against “concrete” partition names. Thus, a concrete partition name may not contain any reserved characters that are used to define regular expressions, for example ‘*’, ‘.’, ‘+’, etc.

For more on regular expressions, see SQL Extension: Regular Expression Matching.

If a PARTITION QoS only contains regular expressions, then the Publisher or Subscriber will be assigned automatically to the default partition with the empty string name (““). Thus, do not be fooled into thinking that a PARTITION QoS that only contains the string “*” matches another PARTITION QoS that only contains the string “*”. Yes, the Publisher will match the Subscriber, but it is because they both belong to the default ““ partition.

DataWriters and DataReaders are considered to have a partition in common if the sets of partitions that their associated Publishers and Subscribers have defined have:

At least one concrete partition name in common

A regular expression in one Entity that matches a concrete partition name in another Entity

The programmatic representation of the PARTITION QoS is shown in . The QosPolicy contains the single string sequence, name. Each element in the sequence can be a concrete name or a regular expression. The Entity will be assigned to the default ““ partition if the sequence is empty.

You can have one long partition string of 256 chars, or multiple shorter strings that add up to 256 or less characters. For example, you can have one string of 4 chars and one string of 252 chars.

Example

Since the set of partitions for a Publisher or Subscriber can be dynamically changed, the Partition QosPolicy is useful to control which DataWriters can send data to which DataReaders and vice versa—even if all of the DataWriters and DataReaders are for the same topic. This facility is useful for creating temporary separation groups among Entities that would otherwise be connected to and exchange data each other.

Note when using Partitions and Durability: If a Publisher changes partitions after startup, it is possible for a reliable, late-joining DataReader to receive data that was written for both the original and the new partition. For example, suppose a DataWriter with TRANSIENT_LOCAL Durability initially writes DDS samples with Partition A, but later changes to Partition B. In this case, a reliable, late-joining DataReader configured for Partition B will receive whatever DDS samples have been saved for the DataWriter. These may include DDS samples which were written when the DataWriter was using Partition A.

The code in Figure 29 illustrates how to change the PARTITION policy.

DDS_PublisherQos publisher_qos;2Note in C, you must initialize the QoS structures before they are used, see Special QosPolicy Handling Considerations for C.
// domain, publisher_listener have been previously created
if (participant->get_default_publisher_qos(publisher_qos) !=
    DDS_RETCODE_OK) {
    // handle error
}
// Set the partition QoS
publisher_qos.partition.name.maximum(3);
publisher_qos.partition.name.length(3);
publisher_qos.partition.name[0] = DDS_String_dup(“partition_A”);
publisher_qos.partition.name[1] = DDS_String_dup(“partition_B”);
publisher_qos.partition.name[2] = DDS_String_dup(“partition_C”);
DDSPublisher* publisher = participant->create_publisher(
	publisher_qos, publisher_listener, DDS_STATUS_MASK_ALL);

The ability to dynamically control which DataWriters are matched to which DataReaders (of the same Topic) offered by the PARTITION QoS can be used in many different ways. Using partitions, connectivity can be controlled based on location-based partitioning, access-control groups, purpose, or a combination of these and other application-defined criteria. We will examine some of these options via concrete examples.

Example of location-based partitions. Assume you have a set of Topics in a traffic management system such as “TrafficAlert,” “AccidentReport,” and “CongestionStatus.” You may want to control the visibility of these Topics based on the actual location to which the information applies. You can do this by placing the Publisher in a partition that represents the area to which the information applies. This can be done using a string that includes the city, state, and country, such as “USA/California/Santa Clara.” A Subscriber can then choose whether it wants to see the alerts in a single city, the accidents in a set of states, or the congestion status across the US. Some concrete examples are shown in .

Example of access-control group partitions. Suppose you have an application where access to the information must be restricted based on reader membership to access-control groups. You can map this group-controlled visibility to partitions by naming all the groups (e.g. executives, payroll, financial, general-staff, consultants, external-people) and assigning the Publisher to the set of partitions that represents which groups should have access to the information. The Subscribers specify the groups to which they belong, and the partition-matching behavior will ensure that the information is only distributed to Subscribers belonging to the appropriate groups. Some concrete examples are shown in .

A slight variation of this pattern could be used to confine the information based on security levels.

Example of purpose-based partitions: Assume an application containing subsystems that can be used for multiple purposes, such as training, simulation, and real use. In some occasions it is convenient to be able to dynamically switch the subsystem from operating in the “simulation world” to the “training world” or to the “real world.” For supervision purposes, it may be convenient to observe multiple worlds, so that you can compare the each one’s results. This can be accomplished by setting a partition name in the Publisher that represents the “world” to which it belongs and a set of partition names in the Subscriber that model the worlds that it can observe.

Properties

This QosPolicy can be modified at any time.

Strictly speaking, this QosPolicy does not have request-offered semantics, although it is matched between DataWriters and DataReaders, and communication is established only if there is a match between partition names.

Related QosPolicies

• DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension).

Applicable DDS Entities

• Publishers
• Subscribers

System Resource Considerations

Partition names are propagated along with the declarations of the DataReaders and the DataWriters and can be examined by user code through built-in topics (see Built-In Topics). Thus the sum-total length of the partition names will impact the bandwidth needed to transmit those declarations, as well as the memory used to store them.

The maximum number of partitions and the maximum number of characters that can be used for the sum-total length of all partition names are configured using the max_partitions and max_partition_cumulative_characters fields of the DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension). Setting more partitions or using longer names than allowed by those limits will result in failure and an INCONSISTENT_QOS_POLICY return code.

However, should you decide to change the maximum number of partitions or maximum cumulative length of partition names, then you must make certain that all applications in the DDS domain have changed the values of max_partitions and max_partition_cumulative_characters to be the same. If two applications have different values for those settings, and one application sets the PARTITION QosPolicy to hold more partitions or longer names than set by another application, then the matching DataWriters and DataReaders of the Publisher and Subscriber between the two applications will not connect. This similar to the restrictions for the GROUP_DATA (GROUP_DATA QosPolicy), USER_DATA (USER_DATA QosPolicy), and TOPIC_DATA (TOPIC_DATA QosPolicy) QosPolicies.

© 2016 RTI