A set of strings that introduces logical PARTITIONs. More...

#include <dds_c_partition_qos.h>

Data Fields
struct DDS_StringSeq	name
	The PARTITION string Sequence.

Detailed Description

A set of strings that introduces logical PARTITIONs.

Only entities that belong to the same PARTITION can communicate with each other.

The PARTITION QoS controls which entities will match which other entities. PARTITIONs prevent entities from communicating. Only entities that belong to the same PARTITION can communicate with each other. The PARTITION QoS policy applies directly to Publishers and Subscribers. DataWriters and DataReaders belong to the partitions of the Publishers and Subscribers that created them.

PARTITION names are propagated with the discovery traffic for Publishers and Subscribers.

DataWriters will make their data available on all PARTITIONs that correspond to their Publisher's PARTITION names, and the DataReaders will see the data on all PARTITIONs that correspond to their Subscriber's PARTITION names. For a DataWriter and DataReader to communicate, the DataWriter's Publisher must match the DataReader's Subscribers PARTITION.

DataWriters and DataReaders will only match with each other if their Publisher's QoS and Subscriber's QoS contain a compatible PARTITION.

The PARTITION sequence must be set before enabling the entity. The user must create a Publisher QoS DDS_PublisherQos::partition or a Subscriber QoS DDS_SubscriberQos::partition for PARTITION configuration.

The default value for a PARTITION is the empty seqeunce. When an entity is created with a DDS_PublisherQos::partition that does not have any concrete strings, meaning it only has regular expressions, then the partition is considered a member of the empty string "".

Publishers and Subscribers without PARTITIONS are considered members of the empty string "".

The regular expression matching rules are as follows: - Two PARTITIONs will match if they are lexicographically identical. - Two PARTITIONs will match if one is a string is not a regular expression and the other is a regular expression that completely matches. - Two regular expressions cannot match.

DDS_PartitionQosPolicy supports the following regular expressions:

* The '*' matches any sequence of characters, including the empty string.

? The '?' character matches the preceding charcter once. Note that the '?' does not conform with the POSIX standard where it is allowed to match zero times.

\ The '\' escape character ***shall*** cause the next character to be interpreted literally.

[ ] Opening and closing brackets '[' ']' matches one of the characters enclosed in the brackets: A range " '[' C0 '-' C1 ']' " matches one character between the collating elements C0 and C1, inclusive.

The "^" and "!" characters placed first in opening and closing brackets matches a single character if the character is not enclosed in the brackets.

A range " '[' '!' C0 '-' C1 ']' " matches a character not in the lexicographically closed interval C0 to C1.

The DDS_PartitionQosPolicy resource limits are made on a per DomainParticipant basis. The resource limits cannot be set individually on a per Publisher/Subscriber basis.

DDS_DomainParticipantResourceLimitsQosPolicy::max_partitions controls the maximum number of PARTITIONs that can be assigned per Publisher/Subscriber.

DDS_DomainParticipantResourceLimitsQosPolicy::max_partition_cumulative_characters controls the maximum number of combined characters in all PARTITION names in a DDS_PartitionQosPolicy.

The maximum number of combined characters should account for a terminating NUL ('\0') character for each partition name string.

DDS_DomainParticipantResourceLimitsQosPolicy::max_partition_string_allocation The maximum number of 8-bit characters reserved for PARTITION.name strings to allocate for the PARTITION. When this is set to DDS_LENGTH_UNLIMITED, no memory is preallocated. Memory is allocated during local and remote entity creation even if the creation occurs during runtime. When max_partition_string_allocation is greater than 0, that amount of memory is preallocated for storing created and discovered PARTITION names. DDS_PartitionQosPolicy.

DDS_DomainParticipantResourceLimitsQosPolicy::max_partition_string_size max_partition_string_size configures the PARTITION name element max string length in local and remote Publishers and Subscribers. All applications in the DDS domain must use the same max_partition_string_size in order to communicate.

When creating a Publisher or Subscriber, all PARTITION elements in the Publisher or Subscriber QoS must not exceed max_partition_string_size or the creation will fail. max_partition_string_size also controls the max length for any discovered PARTITION names from remote Publishers and Subscribers. Remote entities that have PARTITION name lengths that exceed max_partition_string_size will not be discovered.

When max_partition_string_allocation is DDS_LENGTH_UNLIMITED max_partition_string_size should be set to DDS_LENGTH_UNLIMITED. This configuration allows each PARTITION name size to be any length up to max_partition_cumulative_characters. In this configuration, PARTITION strings are allocated and freed during runtime. To prevent allocation during runtime, when max_partition_string_allocation is DDS_LENGTH_UNLIMITED, the users can assert all unique PARTITION names during creation. When any additional instances of that name is encountered, during entity creation or discovery, no further memory is used for storing the existing PARTITION names.

Use the following configurations to completely control memory utilization or to avoid any possibility of runtime allocation.

When max_partition_string_allocation is not DDS_LENGTH_UNLIMITED and max_partition_string_size is DDS_LENGTH_UNLIMITED then PARTITION names can be any length up to max_partition_cumulative_characters. Memory for PARTITION names will be preallocated and will never be freed or reused. The user must have enough max_partition_string_allocation to store every unique instance of each PARTITION name to be discovered.

When max_partition_string_allocation is not DDS_LENGTH_UNLIMITED then max_partition_string_size can be set to a value greater than 0. In this configuration, memory for PARTITION names are preallocated and will never be freed during operation. PARTITION names are stored in memory and consume max_partition_string_size sized memory segments up to max_partition_string_allocation. Memory is reused for PARTITION names that are added to memory, internally deleted, and are no longer needed. As an example, if the application creates a Publisher with a unique PARTITION name instance and then deletes that Publisher, if there are no further uses of that partition name, the application will reuse the memory that was storing the unique PARTITION name. Reuse occurs in the same way for remote entities. The user must have enough max_partition_string_allocation to store every unique instance of each PARTITION name to be created and discovered.

Field Documentation

struct DDS_StringSeq DDS_PartitionQosPolicy::name

The PARTITION string Sequence.

Sequence of strings that introduce a logical PARTITION among the topics visible by the Publisher and Subscriber.

Data Fields

Detailed Description

Field Documentation