dds::core::policy::Partition Class Reference

Set of strings that introduces logical partitions in dds::domain::DomainParticipant, dds::pub::Publisher, or dds::sub::Subscriber entities. More...

#include <dds/core/policy/CorePolicy.hpp>

Public Member Functions
	TPartition ()
	Creates a policy with the default partition. More...
	TPartition (const std::string &partition)
	Creates a policy with a single partition with the specified name. More...
	TPartition (const dds::core::StringSeq &partitions)
	Creates a policy with the partitions specified in a vector. More...
TPartition &	name (const dds::core::StringSeq &partitions)
	Sets the partition names specified in a vector. More...
const dds::core::StringSeq	name () const
	Getter (see setter with the same name) More...

Detailed Description

Set of strings that introduces logical partitions in dds::domain::DomainParticipant, dds::pub::Publisher, or dds::sub::Subscriber entities.

This QoS policy is used to set string identifiers that are used for partitioning entities that would otherwise be connected to and exchange data with each other:

• A dds::pub::DataWriter within a dds::pub::Publisher only communicates with a dds::sub::DataReader in a dds::sub::Subscriber if (in addition to matching the dds::topic::Topic and having compatible QoS) the dds::pub::Publisher and dds::sub::Subscriber have a common partition name string.
• dds::domain::DomainParticipant entities (with the same domain ID and domain tag) are visible to each other only if they have at least one partition name string in common.

Entity:

dds::pub::Publisher, dds::sub::Subscriber, dds::domain::DomainParticipant

Properties:

RxO = NO
Changeable = YES

Usage

The Partition QoS policy provides another way to control which entities will match-and thus communicate with-which other entities. It can be used to prevent entities that would have otherwise matched from talking to each other. Much in the same way that only applications within the same DDS domain will communicate with each other, only entities that belong to the same partition can talk to each other.

The Partition QoS policy allows you to add one or more strings, "partitions", to an entity:

• A DataWriter and DataReader for the same topic are only considered matched if their Publishers and Subscribers have partitions in common (intersecting partitions).
• DomainParticipants (with the same domain ID and domain tag) are visible to each other only if they have at least one partition in common.

Since the set of partitions for an entity can be dynamically changed, the Partition QoS policy is useful for creating temporary separation groups among entities that would otherwise be connected to and exchange data with each other.

DomainParticipant partitions and Publisher/Subscriber partitions are independent of each other. You can use both features independently or in combination to provide the right level of isolation.

Failure to match partitions is not considered an incompatible QoS and does not trigger any listeners or conditions. A change in this policy can potentially modify the "match" of existing DataReader and DataWriter entities. It may establish new "matches" that did not exist before, or break existing matches.

Partition strings are usually directly matched via string comparisons. However, partition strings can also contain wildcard symbols so that partitions can be matched via pattern matching. As long as the partitions or wildcard patterns of an entity intersect with the partitions or wildcard patterns of otherwise matching entities, the entities match; otherwise they do not.

These partition name patterns are regular expressions as defined by the POSIX fnmatch API (1003.2-1992 section B.6). A dds::domain::DomainParticipant, dds::pub::Publisher, or dds::sub::Subscriber entity may include regular expressions in partition names, but no two names that both contain wildcards will ever be considered to match. This means that although regular expressions may be used on the entities, RTI Connext will not try to match two regular expressions.

Each entity must belong to at least one logical partition. A regular expression is not considered to be a logical partition. If an entity has not specified a logical partition, it is assumed to be in the default partition. The default partition is defined to be an empty string (""). Put another way:

• An empty sequence of strings in this QoS policy is considered equivalent to a sequence containing only a single string, the empty string.
• A string sequence that contains only regular expressions and no literal strings, it is treated as if it had an additional element, the empty string.

Partitions are different from creating dds::core::Entity objects in different domains in several ways.

• First, entities belonging to different domains are completely isolated from each other; there is no traffic, meta-traffic or any other way for an application or RTI Connext itself to see entities in a domain it does not belong to.
  
• Second, a dds::core::Entity can only belong to one domain whereas a dds::core::Entity can be in multiple partitions.
  
• Finally, as far as RTI Connext is concerned, each unique data instance is identified by the tuple (DomainID, domain tag, dds::topic::Topic, key). Therefore two dds::core::Entity objects in different domains cannot refer to the same data instance. On the other hand, the same data instance can be made available (published) or requested (subscribed) on one or more partitions.

For more information, see the "PARTITION QosPolicy" section of the Core Libraries User's Manual.

Member Function Documentation

TPartition() [1/3]

dds::core::policy::Partition::TPartition ( )

inline

Creates a policy with the default partition.

TPartition() [2/3]

dds::core::policy::Partition::TPartition ( const std::string &  partition )

inlineexplicit

Creates a policy with a single partition with the specified name.

TPartition() [3/3]

dds::core::policy::Partition::TPartition ( const dds::core::StringSeq &  partitions )

inlineexplicit

Creates a policy with the partitions specified in a vector.

name() [1/2]

TPartition & dds::core::policy::Partition::name ( const dds::core::StringSeq &  partitions )

inline

Sets the partition names specified in a vector.

Several restrictions apply to the partition names in this sequence. A violation of one of the following rules will result in a dds::core::InconsistentPolicyError when setting a dds::pub::Publisher's or dds::sub::Subscriber's QoS.

• A partition name string cannot contain the reserved comma character (',').

• The maximum number of partition name strings allowable in a dds::core::policy::Partition is specified on a domain basis in rti::core::policy::DomainParticipantResourceLimits::max_partitions. The length of this sequence may not be greater than that value.

• The maximum cumulative length of all partition name strings in a dds::core::policy::Partition is specified on a domain basis in rti::core::policy::DomainParticipantResourceLimits::max_partition_cumulative_characters.

[default] Empty sequence (zero-length sequence). Since no logical partition is specified, RTI Connext will assume the entity to be in default partition (empty string partition "").

[range] List of partition name with above restrictions

name() [2/2]

const dds::core::StringSeq dds::core::policy::Partition::name ( ) const

inline

Getter (see setter with the same name)