Instantiates:
<<generic>> FooSeq
See also: DDS.Short
See also: FooSeq

Instantiates:
<<generic>> FooSeq
See also: DDS.Long
See also: FooSeq

Instantiates:
<<generic>> FooSeq
See also: DDS.LongLong
See also: FooSeq

Instantiates:
<<generic>> FooSeq
See also: DDS.UnsignedShort
See also: FooSeq

Instantiates:
<<generic>> FooSeq
See also: DDS.UnsignedLong
See also: FooSeq

Instantiates:
<<generic>> FooSeq
See also: DDS.UnsignedLongLong
See also: FooSeq

Instantiates:
<<generic>> FooSeq
See also: DDS.Float
See also: FooSeq

Instantiates:
<<generic>> FooSeq
See also: DDS.Double
See also: FooSeq

Instantiates:
<<generic>> FooSeq
See also: DDS.LongDouble
See also: FooSeq

Instantiates:
<<generic>> FooSeq
See also: DDS.Char
See also: FooSeq

Instantiates:
<<generic>> FooSeq
See also: DDS.Wchar
See also: FooSeq

Instantiates:
<<generic>> FooSeq
See also: DDS.Octet
See also: FooSeq

Instantiates:
<<generic>> FooSeq
See also: DDS_Octets

Instantiates:
<<generic>> FooSeq
See also: DDS.Boolean
See also: FooSeq

StringSeq is a sequence that contains strings.

Instantiates:
<<generic>> FooSeq
See also: FooSeq

Instantiates:
<<generic>> FooSeq
See also: DDS_KeyedString

Instantiates:
<<generic>> FooSeq
See also: DDS_KeyedOctets

Instantiates:
<<generic>> FooSeq
See also: DDS.Wchar
See also: DDS.StringSeq
See also: FooSeq

When reading into this sequence (as with DDS.DataWriter.get_matched_subscriptions or DDS.DataReader.get_matched_publications), the contents of any existing handles in this sequence will be overwritten to avoid the expense of allocating new handles. Therefore, it is generally not a good idea to add handles to a sequence that you obtained elsewhere (e.g. from a Status object or as a result of calling FooDataWriter.register_instance). Any null elements will be replaced by new handles. To avoid allocating new handles on the fly, use the procedure DDS_InstanceHandleSeq.fill.

Instantiates:
<<generic>> FooSeq
See also: DDS.InstanceHandle_t
See also: FooSeq

Instantiates:
<<generic>> FooSeq

See also: DDS.QosPolicyCount

See also: DDS.Tag

Instantiates:
<<generic>> FooSeq

See also: DDS.TransportUnicastSettings_t

Instantiates:
<<generic>> FooSeq

See also: DDS.TransportMulticastSettings_t

Instantiates:
<<generic>> FooSeq

See also: DDS.TransportMulticastMapping_t

See also: DDS.DataRepresentationId_t

See also: DDS.Locator_t

A sequence of DDS.LocatorFilter_t used to report the channels' properties. If the length of the sequence is zero, the DDS.MultiChannelQosPolicy is not in use.

Instantiates:
<<generic>> FooSeq

See also: DDS.LocatorFilter_t

A sequence of DDS.ChannelSettings_t used to configure the channels' properties. If the length of the sequence is zero, the DDS.MultiChannelQosPolicy has no effect.

Instantiates:
<<generic>> FooSeq

See also: DDS.ChannelSettings_t

See also: DDS.Property_t

In the context of Collaborative DataWriters, it can be used by a DDS.DataReader to define a group of remote DataWriters that the DDS.DataReader will wait to discover before skipping missing samples.

In the context of Durable Subscriptions, it can be used to create a set of Durable Subscriptions identified by a name and a quorum count.

Instantiates:
<<generic>> FooSeq
See also: DDS.EndpointGroup_t

See also: FooSeq

Instantiates:
<<generic>> FooSeq
See also: DDS.TransportInfo_t

Instantiates:
<<generic>> FooSeq
See also: DDS.ParticipantBuiltinTopicData

Instantiates:
<<generic>> FooSeq
See also: DDS.TopicBuiltinTopicData

Instantiates:
<<generic>> FooSeq
See also: DDS.PublicationBuiltinTopicData

Instantiates:
<<generic>> FooSeq
See also: DDS.SubscriptionBuiltinTopicData

See also: FooSeq

You must set certain members in a consistent manner:

length of DDS.TopicQos.topic_data .value <= DDS.DomainParticipantQos.resource_limits .topic_data_max_length

If any of the above are not true, DDS.Topic.set_qos, DDS.Topic.set_qos_with_profile and DDS.DomainParticipant.set_default_topic_qos will fail with DDS.RETCODE_INCONSISTENT_POLICY and DDS.DomainParticipant.create_topic will return NULL.

Entity:
DDS.Topic

See also: DDSQosTypesModule allowed ranges within each Qos.

Topic_Data: Topic data policy, DDSTopicDataQosModule.

Durability: Durability policy, DDSDurabilityQosModule.

Durability_Service: DurabilityService policy, DDSDurabilityServiceQosModule.

Deadline: Deadline policy, DDSDeadlineQosModule.

Latency_Budget: Latency budget policy, DDSLatencyBudgetQosModule.

Liveliness: Liveliness policy, DDSLivelinessQosModule.

Reliability: Reliability policy, DDSReliabilityQosModule.

Destination_Order: Destination order policy, DDSDestinationOrderQosModule.

History: History policy, DDSHistoryQosModule.

Resource_Limits: Resource limits policy, DDSResourceLimitsQosModule.

Transport_Priority: Transport priority policy, DDSTransportPriorityQosModule.

Lifespan: Lifespan policy, DDSLifespanQosModule.

Ownership: Ownership policy, DDSOwnershipQosModule.

Representation: Data representation policy, DDSDataRepresentationQosModule.

You must set certain members in a consistent manner:

- DDS.DataWriterQos.history .depth <= DDS.DataWriterQos.resource_limits .max_samples_per_instance

- DDS.DataWriterQos.resource_limits .max_samples_per_instance <= DDS.DataWriterQos.resource_limits .max_samples

- DDS.DataWriterQos.resource_limits .initial_samples <= DDS.DataWriterQos.resource_limits .max_samples

- DDS.DataWriterQos.resource_limits .initial_instances <= DDS.DataWriterQos.resource_limits .max_instances

- length of DDS.DataWriterQos.user_data .value <= DDS.DomainParticipantQos.resource_limits .writer_user_data_max_length

If any of the above are not true, DDS.DataWriter.set_qos and DDS.DataWriter.set_qos_with_profile \endif and DDS.Publisher.set_default_datawriter_qos and DDS.Publisher.set_default_datawriter_qos_with_profile will fail with DDS.RETCODE_INCONSISTENT_POLICY and \ifnot CPP2_LANGUAGE_ONLY DDS.Publisher.create_datawriter and DDS.Publisher.create_datawriter_with_profile and will return NULL.

Entity:
DDS.DataWriter

See also: DDSQosTypesModule allowed ranges within each Qos.

Durability: Durability policy, DDSDurabilityQosModule.

Durability_Service: DurabilityService policy, DDSDurabilityServiceQosModule.

Deadline: Deadline policy, DDSDeadlineQosModule.

Latency_Budget: Latency budget policy, DDSLatencyBudgetQosModule.

Liveliness: Liveliness policy, DDSLivelinessQosModule.

Reliability: Reliability policy, DDSReliabilityQosModule.

Destination_Order: Destination order policy, DDSDestinationOrderQosModule.

History: History policy, DDSHistoryQosModule.

Resource_Limits: Resource limits policy, DDSResourceLimitsQosModule.

Transport_Priority: Transport priority policy, DDSTransportPriorityQosModule.

Lifespan: Lifespan policy, DDSLifespanQosModule.

User_Data: User data policy, DDSUserDataQosModule.

Ownership: Ownership policy, DDSOwnershipQosModule.

Ownership_Strength: Ownership strength policy, DDSOwnershipStrengthQosModule.

Writer_Data_Lifecycle: Writer data lifecycle policy, DDSWriterDataLifecycleQosModule.

Representation: Data representation policy, DDSDataRepresentationQosModule.

Data_Tags: DataTag policy, DDSDataTagQosModule.

Writer_Resource_Limits: <<ext>> Writer resource limits policy, DDSDataWriterResourceLimitsQosModule.

Protocol: <<ext>> DDS.DataWriter protocol policy, DDSDataWriterProtocolQosModule

Transport_Selection: <<ext>> Transport plugin selection policy, DDSTransportSelectionQosModule.

Specifies the transports available for use by the DDS.DataWriter.

Unicast: <<ext>> Unicast transport policy, DDSTransportUnicastQosModule.

Specifies the unicast transport interfaces and ports on which messages can be received.

The unicast interfaces are used to receive messages from DDS.DataReader entities in the domain.

Encapsulation: <<ext>> Transport encapsulation policy, DDSTransportEncapsulationQosModule

Specifies data encapsulation formats supported per transport instance of a DDS.DataWriter or DDS.DataReader.

Publish_Mode: <<ext>> Publish mode policy, DDSPublishModeQosModule.

Determines whether the DDS.DataWriter publishes data synchronously or asynchronously and how.

Property: <<ext>> Property policy, DDSPropertyQosModule.

Service: <<ext>> Service policy, DDSServiceQosModule.

batch: <<ext>> Batch policy, DDSBatchQosModule.

multi_channel: <<ext>> Multi channel policy, DDSMultiChannelQosModule.

Availability: <<ext>> Availability policy, DDSAvailabilityQosModule.

publication_name: <<ext>> EntityName policy, DDSEntityNameQosModule.

Topic_Query_Dispatch: <<ext>> Topic Query dispatch policy, DDSTopicQueryDispatchQosModule.

Transfer_Mode: <<ext>> TransferMode policy, DDSDataWriterTransferModeQosModule.

Type_Support: <<ext>> Type support data, DDSTypeSupportQosModule.

Optional value that is passed to a type plugin's on_endpoint_attached and serialization functions.

You must set certain members in a consistent manner:

length of DDS.GroupDataQosPolicy.value <= DDS.DomainParticipantResourceLimitsQosPolicy.publisher_group_data_max_length

length of DDS.PartitionQosPolicy.name <= DDS.DomainParticipantResourceLimitsQosPolicy.max_partitions

combined number of characters (including terminating 0) in DDS.PartitionQosPolicy.name <= DDS.DomainParticipantResourceLimitsQosPolicy.max_partition_cumulative_characters

If any of the above are not true, DDS.Publisher.set_qos and DDS.Publisher.set_qos_with_profile will fail with DDS.RETCODE_INCONSISTENT_POLICY and DDS.DomainParticipant.create_publisher will\ return NULL.

Presentation: Presentation policy, DDSPresentationQosModule.

Partition: Partition policy, DDSPartitionQosModule.

Group_Data: Group data policy, DDSGroupDataQosModule.

Entity_Factory: Entity factory policy, DDSEntityFactoryQosModule.

Asynchronous_Publisher: <<ext>> Asynchronous publishing settings for the DDS.Publisher and all entities that are created by it.

Exclusive_Area: <<ext>> Exclusive area for the DDS.Publisher and all entities that are created by it.

publisher_name: <<ext>> EntityName policy, DDSEntityNameQosModule.

You must set certain members in a consistent manner:

DDS.DataReaderQos.deadline .period >= DDS.DataReaderQos.time_based_filter .minimum_separation

DDS.DataReaderQos.history .depth <= DDS.DataReaderQos.resource_limits .max_samples_per_instance

DDS.DataReaderQos.resource_limits .max_samples_per_instance <= DDS.DataReaderQos.resource_limits .max_samples DDS.DataReaderQos.resource_limits .initial_samples <= DDS.DataReaderQos.resource_limits .max_samples

DDS.DataReaderQos.resource_limits .initial_instances <= DDS.DataReaderQos.resource_limits .max_instances

DDS.DataReaderQos.reader_resource_limits .initial_remote_writers_per_instance <= DDS.DataReaderQos.reader_resource_limits .max_remote_writers_per_instance

DDS.DataReaderQos.reader_resource_limits .initial_infos <= DDS.DataReaderQos.reader_resource_limits .max_infos

DDS.DataReaderQos.reader_resource_limits .max_remote_writers_per_instance <= DDS.DataReaderQos.reader_resource_limits .max_remote_writers

DDS.DataReaderQos.reader_resource_limits .max_samples_per_remote_writer <= DDS.DataReaderQos.resource_limits .max_samples

length of DDS.DataReaderQos.user_data .value <= DDS.DomainParticipantQos.resource_limits .reader_user_data_max_length

If any of the above are not true, DDS.DataReader.set_qos and DDS.DataReader.set_qos_with_profile \endif will fail with DDS.RETCODE_INCONSISTENT_POLICY and \ifnot CPP2_LANGUAGE_ONLY DDS.Subscriber.create_datareader will return NULL.

Durability: Durability policy, DDSDurabilityQosModule.

Deadline: Deadline policy, DDSDeadlineQosModule.

Latency_Budget: Latency budget policy, DDSLatencyBudgetQosModule.

Liveliness: Liveliness policy, DDSLivelinessQosModule.

Reliability: Reliability policy, DDSReliabilityQosModule.

Destination_Order: Destination order policy, DDSDestinationOrderQosModule.

History: History policy, DDSHistoryQosModule.

Resource_Limits: Resource limits policy, DDSResourceLimitsQosModule.

User_Data: User data policy, DDSUserDataQosModule.

Ownership: Ownership policy, DDSOwnershipQosModule.

Time_Based_Filter: Time-based filter policy, DDSTimeBasedFilterQosModule

Reader_Data_Lifecycle: Reader data lifecycle policy, DDSReaderDataLifecycleQosModule

Representation: Data representation policy, DDSDataRepresentationQosModule.

Type_Consistency: Type consistency enforcement policy, DDSTypeConsistencyEnforcementQosModule

Data_Tags: DataTag policy, DDSDataTagQosModule.

Reader_Resource_Limits: <<ext>> DDS.DataReader resource limits policy, DDSDataReaderResourceLimitsQosModule. This policy is an extension to the DDS standard.

Protocol: <<ext>> DDS.DataReader protocol policy, DDSDataReaderProtocolQosModule

Transport_Selection: <<ext>> Transport selection policy, DDSTransportSelectionQosModule.

Specifies the transports available for use by the DDS.DataReader.

Unicast: <<ext>> Unicast transport policy, DDSTransportUnicastQosModule.

Specifies the unicast transport interfaces and ports on which messages can be received.

The unicast interfaces are used to receive messages from DDS.DataWriter entities in the domain.

Multicast: <<ext>> Multicast transport policy, DDSTransportMulticastQosModule.

Specifies the multicast group addresses and ports on which messages can be received.

The multicast addresses are used to receive messages from DDS.DataWriter entities in the domain.

Property: <<ext>> Property policy, DDSPropertyQosModule.

Service: <<ext>> Service policy, DDSServiceQosModule.

Availability: <<ext>> Availability policy, DDSAvailabilityQosModule.

Subscription_Name: <<ext>> EntityName policy, DDSEntityNameQosModule.

Transport_Priority: Transport priority policy, DDSTransportPriorityQosModule.

Type_Support: <<ext>> type support data, DDSTypeSupportQosModule.

Optional value that is passed to a type plugin's on_endpoint_attached and deserialization functions.

You must set certain members in a consistent manner:

length of DDS.GroupDataQosPolicy.value <= DDS.DomainParticipantResourceLimitsQosPolicy.subscriber_group_data_max_length

length of DDS.PartitionQosPolicy.name <= DDS.DomainParticipantResourceLimitsQosPolicy.max_partitions

combined number of characters (including terminating 0) in DDS.PartitionQosPolicy.name <= DDS.DomainParticipantResourceLimitsQosPolicy.max_partition_cumulative_characters

If any of the above are not true, DDS.Subscriber.set_qos and DDS.Subscriber.set_qos_with_profile will fail with DDS.RETCODE_INCONSISTENT_POLICY

Presentation: Presentation policy, DDSPresentationQosModule.

Partition: Partition policy, DDSPartitionQosModule.

Group_Data: Group data policy, DDSGroupDataQosModule.

Entity_Factory: Entity factory policy, DDSEntityFactoryQosModule.

Enclusive_Area: <<ext>> Exclusive area for the subscriber and all entities that are created by the subscriber.

subscriber_name: <<ext>> EntityName policy, DDSEntityNameQosModule.

Certain members must be set in a consistent manner:

Length of DDS.DomainParticipantQos.user_data .value <= DDS.DomainParticipantQos.resource_limits .participant_user_data_max_length

For DDS.DomainParticipantQos.discovery_config .publication_writer
high_watermark <= DDS.DomainParticipantQos.resource_limits .local_writer_allocation .max_count heartbeats_per_max_samples <= DDS.DomainParticipantQos.resource_limits .local_writer_allocation.max_count

For DDS.DomainParticipantQos.discovery_config .suscription_writer
high_watermark <= DDS.DomainParticipantQos.resource_limits .local_reader_allocation.max_count heartbeats_per_max_samples <= DDS.DomainParticipantQos.resource_limits .local_reader_allocation.max_count

If any of the above are not true, DDS.DomainParticipant.set_qos and DDS.DomainParticipant.set_qos_with_profile and DDS.DomainParticipantFactory.set_default_participant_qos will fail with DDS.RETCODE_INCONSISTENT_POLICY, and DDS.DomainParticipantFactory.create_participant will fail.

Entity:
DDS.DomainParticipant

See also: DDSQosTypesModule and allowed ranges within each Qos.

See also: NDDS_DISCOVERY_PEERS

User_Data: User data policy, DDSUserDataQosModule.

Entity_Factory: Entity factory policy, DDSEntityFactoryQosModule.

Wire_Protocol: <<ext>> Wire Protocol policy, DDSWireProtocolQosModule.

The wire protocol (RTPS) attributes associated with the participant.

Transport_Builtin: <<ext>> Transport Builtin policy, DDSTransportBuiltinQosModule.

Default_Unicast: <<ext>> Default Unicast Transport policy, DDSTransportUnicastQosModule.

Discovery: <<ext>> Discovery policy, DDSDiscoveryQosModule.

Resource_Limits: <<ext>> Domain participant resource limits policy, DDSDomainParticipantResourceLimitsQosModule.

Event: <<ext>> Event policy, DDSEventQosModule.

Receiver_Pool: <<ext>> Receiver pool policy, DDSReceiverPoolQosModule.

Database: <<ext>> Database policy, DDSDatabaseQosModule.

Discovery_Config: <<ext>> Discovery config policy, DDSDiscoveryConfigQosModule.

Exclusive_Area: <<ext>> Exclusive area for the domain and all entities that are created by the domain.

Property: <<ext>> Property policy, DDSPropertyQosModule.

Participant_Name: <<ext>> The participant name. DDSEntityNameQosModule

Multicast_Mapping: <<ext>> The multicast mapping policy. DDSTransportMulticastMappingQosModule

User_Object: <<ext>> Size and alignment of user object stored in each entity. DDSUserObjectModule.

Type_Support: <<ext>> Type support data, DDSTypeSupportQosModule.

Optional value that is passed to a type plugin's on_participant_attached function.

Entity:
DDS.DomainParticipantFactory

See also: DDSQosTypesModule and allowed ranges within each Qos.

Entity_Factory: Entity factory policy, DDSEntityFactoryQosModule.

Resource_Limits: <<ext>> System resource limits, DDSSystemResourceLimitsQosModule.

Note: This QoS policy cannot be configured from XML configuration files.

Profile: <<ext>> Qos profile policy, DDSProfileQosModule.

Note: This QoS policy cannot be configured from XML configuration files.

Logging: <<ext>> Logging qos policy, DDSLoggingQosModule.

A 16-bit signed short integer value.

A 32-bit signed long integer value.

A 64-bit signed long long integer value.

A 16-bit unsigned short integer value.

A 32-bit unsigned long integer value.

A 64-bit unsigned long long integer value.

Encoded as a signed 32-bit integer value. By default, the first enum identifier has the numeric value zero (0) (unless the value is provided explicitly). Successive enum identifiers take ascending numeric values, in order of declaration from left to right.

A 32-bit floating-point value.

A 64-bit floating-point value.

A 128-bit floating-point value.

An 8-bit quantity that encodes a single byte charater from any byte-oriented code set.

A 16-bit quantity that contains a wide character encoded in UTF-16.

An 8-bit quantity that is guaranteed not to undergo any conversion when transmitted by the middleware.

length: Number of octets to serialize.

value: DDS_Octets array value.

An 8-bit Boolean value that is used to denote a data item that can only take one of the values DDS.BOOLEAN_TRUE (1) or DDS.BOOLEAN_FALSE (0).

Has a range of ISO Latin-1 (except ASCII NULL) and a variable length.

key: Instance key associated with the specified value.

value: String value.

key: Instance key associated with the specified value.

length: Number of octets to serialize.

value: DDS_Octets array value.

Participants with the same DDS.DomainId_t are said to be in the same domain, and can thus communicate with one another.

The lower limit for a domain ID is 0. The upper limit for a domain ID is determined by the guidelines stated in DDS.RtpsWellKnownPorts_t (specifically DDS.RtpsWellKnownPorts_t.domain_id_gain)

A DDS.Time_t represents a moment in time.

Sec: seconds

Nanosec: nanoseconds

[range] [0,1000000000)

Represents a time interval.

Sec: seconds

Nanosec: nanoseconds

[range] [0,1000000000)

QoS:
DDS.DataRepresentationQosPolicy

Compression_Ids: <<ext>> Mask that represents the compression algorithms enabled.

A bitmap that represents the compression algorithm IDs (DDS.CompressionIdMask) that are supported by the endpoint. The DDS.DataWriter creation will fail if more than one algorithm is provided.

If a DDS.DataWriter inherits multiple compression IDs from a DDS.Topic, only the least significant bit enabled will be inherited. This forces the following order of preference: DDS_COMPRESSION_ID_ZLIB, DDS_COMPRESSION_ID_BZIP2, DDS_COMPRESSION_ID_LZ4.

Interactions with Security and Batching: Currently, the only algorithm that is supported when compression and batching are enabled on the same DDS.DataWriter is DDS_COMPRESSION_ID_ZLIB.

The combination of compression, batching and data protection is not supported. Please consider using RTPS protection instead of data protection if compression and batching are required. The reason behind this restriction is that when using batching, compression is applied to the entire batch, while data protection is applied to each of the batch samples individually. Compressing already encrypted data results in an expansion of the data instead of a reduction of it because encrypted data does not lend itself to compression. Therefore this combination is not supported and will result in a DataWriter creation error.

Note: When DDS.DataWriterProtocolQosPolicy.serialize_key_with_dispose is enabled and a dispose message is sent, the serialized key is not compressed.

[default] For DDS.Topic, DDS.DataWriter a DDS.CompressionIdMask mask set to DDS_COMPRESSION_ID_MASK_NONE

[default] For DDS.DataReader a DDS.CompressionIdMask mask set to DDS_COMPRESSION_ID_MASK_ALL.

Writer_Compression_Level: <<ext>> The level of compression to use when compressing data.

Compression algorithms typically allow you to choose a level with which to compress the data. Each level has trade-offs between the resulting compression ratio and the speed of compression.

[range] [0, 10]

The value 1 represents the fastest compression time and the lowest compression ratio. The value 10 represents the slowest compression time but the highest compression ratio.

A value of 0 disables compression.

[default] DDS_COMPRESSION_LEVEL_BEST_COMPRESSION

Note: Only available for a DDS.DataWriter and DDS.Topic.

Writer_Compression_Threshold: <<ext>> The threshold, in bytes, above which a serialized sample will be eligible to be compressed.

Any sample with a serialized size greater than or equal to the threshold will be eligible to be compressed. All samples with an eligible serialized size will be compressed. Only if the compressed size is smaller than the serialized size will the sample be stored and sent compressed on the wire.

For batching we check the maximum serialized size of the batch, calculated as serialized_sample_max_size * DDS.BatchQosPolicy.max_samples

[range] [0, 2147483647] or DDS.LENGTH_UNLIMITED

Setting the threshold to DDS.LENGTH_UNLIMITED disables the compression.

[default] DDS_COMPRESSION_THRESHOLD_DEFAULT (8192)

Note: Only available for a DDS.DataWriter and DDS.Topic.

Handle to identify different instances of the same DDS.Topic of a certain type.

See also: FooDataWriter.register_instance
See also: DDS.SampleInfo.instance_handle

Represents a 128 bit GUID.

Value: A 16 byte array containing the GUID value

Represents a 64-bit sequence number.

High: The most significant part of the sequence number

Low: The least significant part of the sequence number

Each concrete DDS.Entity is associated with a set of *Status objects whose values represent the communication status of that DDS.Entity.

The communication statuses whose changes can be communicated to the application depend on the DDS.Entity.

Each status value can be accessed with a corresponding procedure on the DDS.Entity. The changes on these status values cause activation of the corresponding DDS.StatusCondition objects and trigger invocation of the proper DDS.Listener objects to asynchronously inform the application. Note that not all statuses will activate the DDS.StatusCondition or have a corresponding listener callback. Refer to the documentation of the individual statuses for that information.

See also: DDS.Entity, DDS.StatusCondition, DDS.Listener

The bit-mask is an efficient and compact representation of a fixed-length list of DDS.StatusKind values.

Bits in the mask correspond to different statuses. You can choose which changes in status will trigger a callback by setting the corresponding status bits in this bit-mask and installing callbacks for each of those statuses.

The bits that are true indicate that the listener will be called back for changes in the corresponding status.

Bits in the mask correspond to different statuses. You can choose which changes in status will trigger a callback by setting the corresponding status bits in this bit-mask and installing callbacks for each of those statuses.

The bits that are true indicate that the listener will be called back for changes in the corresponding status.

See also: DDS.ThreadSettings_t

Controlling CPU Core Affinity for RTI Threads

Most thread-related QoS settings apply to a single thread (such as for the DDS.EventQosPolicy, DDS.DatabaseQosPolicy, and DDS.AsynchronousPublisherQosPolicy). However, the thread settings in the DDS.ReceiverPoolQosPolicy control every receive thread created. In this case, there are several schemes to map M threads to N processors; the rotation kind controls which scheme is used.

Controlling CPU Core Affinity is only relevant to the DDS.ReceiverPoolQosPolicy. It is ignored within other QoS policies that include DDS.ThreadSettings_t.

If DDS.ThreadSettings_t.cpu_list is empty, the rotation is irrelevant since no affinity adjustment will occur. Suppose instead that DDS.ThreadSettings_t.cpu_list = {0, 1} and that the middleware creates three receive threads: {A, B, C}. If DDS.ThreadSettings_t.cpu_rotation is DDS.THREAD_SETTINGS_CPU_NO_ROTATION, threads A, B and C will have the same processor affinities (0-1), and the OS will control thread scheduling within this bound. It is common to denote CPU affinities as a bitmask, where set bits represent allowed processors to run on. This mask is printed in hex, so a CPU core affinity of 0-1 can be represented by the mask 0x3.

If DDS.ThreadSettings_t.cpu_rotation is DDS.THREAD_SETTINGS_CPU_RR_ROTATION, each thread will be assigned in round-robin fashion to one of the processors in DDS.ThreadSettings_t.cpu_list; perhaps thread A to 0, B to 1, and C to 0. Note that the order in which internal middleware threads spawn is unspecified.

Not all of these options may be relevant for all operating systems. Refer to the Platform Notes for further information.

QoS:
DDS.EventQosPolicy DDS.DatabaseQosPolicy DDS.ReceiverPoolQosPolicy DDS.AsynchronousPublisherQosPolicy

Mask: Describes the type of thread.

The meaning of each bit of the mask are defined by DDS.ThreadSettingsKind.

[default] 0, use default options of the OS

Priority: Thread priority.

Important: The interpretation of numeric thread priority values is different based on whether the priority is specified in your application code or in an XML QoS profile document. This is because QoS profile documents are intended to be usable across programming languages.

[range] java.lang.Thread.MIN_PRIORITY to MAX_PRIORITY if set programmatically in Java code ange Platform-dependent - Consult Platform Notes for additional details. if set in a QoS profile document

Stack_Size: The thread stack-size.

[range] Platform-dependent. Consult Platform Notes for additional details.

Cpu_List: The list of processors on which the thread(s) may run.

A sequence of integers that represent the set of processors on which the thread(s) controlled by this QoS may run. An empty sequence (the default) means the middleware wlll make no CPU affinity adjustments.

Note: This feature is currently only supported on a subset of architectures (see the Platform Notes ). The API may change as more architectures are added in future releases.

This value is only relevant to the DDS.ReceiverPoolQosPolicy. It is ignored within other QoS policies that include DDS.ThreadSettings_t.

See also: ThreadSettingsCpuRotationKind_usage

[default] Empty sequence

Cpu_Rotation: Determines how processor affinity is applied to multiple threads.

This value is only relevant to the DDS.ReceiverPoolQosPolicy. It is ignored within other QoS policies that include DDS.ThreadSettings_t.

See also: ThreadSettingsCpuRotationKind_usage

Note: This feature is currently only supported on a subset of architectures (see the Platform Notes ). The API may change as more architectures are added in future releases.

Policy_Id: The QosPolicy ID

Count: a counter

Entity:
DDS.DomainParticipant, DDS.DataReader, DDS.DataWriter

Properties:
"Rx0" = NO;
"Changeable" = "YES"

See also: DDS.DomainParticipant.get_builtin_subscriber

Usage

The purpose of this QoS is to allow the application to attach additional information to the created DDS.Entity objects, so that when a remote application discovers their existence, it can access that information and use it for its own purposes. This information is not used by dds.

One possible use of this QoS is to attach security credentials or some other information that can be used by the remote application to authenticate the source.

In combination with operations such as DDS.DomainParticipant.ignore_participant, DDS.DomainParticipant.ignore_publication, DDS.DomainParticipant.ignore_subscription, and DDS.DomainParticipant.ignore_topic, this QoS policy can assist an application to define and enforce its own security policies.

The use of this QoS is not limited to security; it offers a simple, yet flexible extensibility mechanism.

Important: RTI Connext stores the data placed in this policy in pre-allocated pools. It is therefore necessary to configure RTI Connext with the maximum size of the data that will be stored in policies of this type. This size is configured with DDS.DomainParticipantResourceLimitsQosPolicy.participant_user_data_max_length, DDS.DomainParticipantResourceLimitsQosPolicy.writer_user_data_max_length, and DDS.DomainParticipantResourceLimitsQosPolicy.reader_user_data_max_length.

Value: a sequence of octets

[default] empty (zero-length)

[range] Octet sequence of length [0,max_length]

Entity:
DDS.Topic

Properties:
"Rx0" = NO
"Changeable" = "YES"

See also: DDS.DomainParticipant.get_builtin_subscriber

Usage

The purpose of this QoS is to allow the application to attach additional information to the created DDS.Topic objects, so that when a remote application discovers their existence, it can access that information and use it for its own purposes. This extra data is not used by dds.

One possible use of this QoS is to attach security credentials or some other information that can be used by the remote application to authenticate the source.

In combination with DDS.DataReaderListener, DDS.DataWriterListener, or operations such as DDS.DomainParticipant.ignore_topic, this QoS policy can assist an application in defining and enforcing its own security policies.

The use of this QoS is not limited to security; it offers a simple, yet flexible extensibility mechanism.

Important: RTI Connext stores the data placed in this policy in pre-allocated pools. It is therefore necessary to configure RTI Connext with the maximum size of the data that will be stored in policies of this type. This size is configured with DDS.DomainParticipantResourceLimitsQosPolicy.topic_data_max_length.

Value: a sequence of octets

[default] empty (zero-length)

[range] Octet sequence of length [0,max_length]

Entity:
DDS.DataReader DDS.DataWriter

Properties:
"Rx0" = N/A;
"Changeable" = "NO"

Usage

The DATA_TAG QoS policy can be used to associate a set of tags in the form of (name, value) pairs with a DDS.DataReader or DDS.DataWriter. This is similar to the DDS.PropertyQosPolicy, except for the following differences:

Entity:
DDS.Publisher, DDS.Subscriber

Properties:
"Rx0" = NO
"Changeable" = "YES"

See also: DDS.DomainParticipant.get_builtin_subscriber

Usage

The additional information is attached to a DDS.Publisher or DDS.Subscriber. This extra data is not used by RTI Connext itself. When a remote application discovers the DDS.Publisher or DDS.Subscriber, it can access that information and use it for its own purposes.

Use cases for this QoS policy, as well as the DDS.TopicDataQosPolicy and DDS.UserDataQosPolicy, are often application-to-application identification, authentication, authorization, and encryption purposes. For example, applications can use Group or User Data to send security certificates to each other for RSA-type security.

In combination with DDS.DataReaderListener, DDS.DataWriterListener and operations such as DDS.DomainParticipant.ignore_publication and DDS.DomainParticipant.ignore_subscription, this QoS policy can help an application to define and enforce its own security policies. For example, an application can implement matching policies similar to those of the DDS.PartitionQosPolicy, except the decision can be made based on an application-defined policy.

The use of this QoS is not limited to security; it offers a simple, yet flexible extensibility mechanism.

Important: RTI Connext stores the data placed in this policy in pre-allocated pools. It is therefore necessary to configure RTI Connext with the maximum size of the data that will be stored in policies of this type. This size is configured with DDS.DomainParticipantResourceLimitsQosPolicy.publisher_group_data_max_length and DDS.DomainParticipantResourceLimitsQosPolicy.subscriber_group_data_max_length.

Value: a sequence of octets

[default] Empty (zero-sized)

[range] Octet sequence of length [0,max_length]

QoS:
DDS.DurabilityQosPolicy

Entity:
DDS.Topic, DDS.DataReader, DDS.DataWriter

Status:
DDS.OFFERED_INCOMPATIBLE_QOS_STATUS, DDS.REQUESTED_INCOMPATIBLE_QOS_STATUS

Properties:
"Rx0" = YES
"Changeable" = "UNTIL ENABLE"

See also: DDSDurabilityServiceQosModule

Usage

It is possible for a DDS.DataWriter to start publishing data before all (or any) DDS.DataReader entities have joined the network.

Moreover, a DDS.DataReader that joins the network after some data has been written could potentially be interested in accessing the most current values of the data, as well as potentially some history.

This policy makes it possible for a late-joining DDS.DataReader to obtain previously published samples.

By helping to ensure that DataReaders get all data that was sent by DataWriters, regardless of when it was sent, using this QoS policy can increase system tolerance to failure conditions.

Note that although related, this does not strictly control what data RTI Connext will maintain internally. That is, RTI Connext may choose to maintain some data for its own purposes (e.g., flow control) and yet not make it available to late-joining readers if the DDSDurabilityQosModule policy is set to DDS.VOLATILE_DURABILITY_QOS.

Transient and Persistent Durability

For the purpose of implementing the DURABILITY QoS kind TRANSIENT or PERSISTENT, RTI Connext behaves as if for each Topic that has DDS.DurabilityQosPolicy.kind of DDS.TRANSIENT_DURABILITY_QOS or DDS.PERSISTENT_DURABILITY_QOS there is a corresponding "built-in" DDS.DataReader and DDS.DataWriter configured with the same DURABILITY kind. In other words, it is as if somewhere in the system, independent of the original DDS.DataWriter, there is a built-in durable DDS.DataReader subscribing to that Topic and a built-in durable DataWriter re-publishing it as needed for the new subscribers that join the system. This functionality is provided by the RTI Persistence Service.

The Persistence Service can configure itself based on the QoS of your application's DDS.DataWriter and DDS.DataReader entities. For each transient or persistent DDS.Topic, the built-in fictitious Persistence Service DDS.DataReader and DDS.DataWriter have their QoS configured from the QoS of your application's DDS.DataWriter and DDS.DataReader entities that communicate on that DDS.Topic.

For a given DDS.Topic, the usual request/offered semantics apply to the matching between any DDS.DataWriter in the domain that writes the DDS.Topic and the built-in transient/persistent DDS.DataReader for that DDS.Topic; similarly for the built-in transient/persistent DDS.DataWriter for a DDS.Topic and any DDS.DataReader for the DDS.Topic. As a consequence, a DDS.DataWriter that has an incompatible QoS will not send its data to the RTI Persistence Service, and a DDS.DataReader that has an incompatible QoS will not get data from it.

Incompatibilities between local DDS.DataReader and DDS.DataWriter entities and the corresponding fictitious built-in transient/persistent entities cause the DDS.REQUESTED_INCOMPATIBLE_QOS_STATUS and DDS.OFFERED_INCOMPATIBLE_QOS_STATUS to change and the corresponding Listener invocations and/or signaling of DDS.Condition objects as they would with your application's own entities.

The value of DDS.DurabilityServiceQosPolicy.service_cleanup_delay controls when RTI Persistence Service is able to remove all information regarding a data instances.

Information on a data instance is maintained until the following conditions are met:

1. The instance has been explicitly disposed (instance_state = NOT_ALIVE_DISPOSED),

and

2. All samples for the disposed instance have been acknowledged, including the dispose sample itself,

and

3. A time interval longer that DDS.DurabilityServiceQosPolicy.service_cleanup_delay has elapsed since the moment RTI Connext detected that the previous two conditions were met. (Note: Only values of zero or DDS_DURATION_INFINITE are currently supported for the service_cleanup_delay)

The utility of DDS.DurabilityServiceQosPolicy.service_cleanup_delay is apparent in the situation where an application disposes an instance and it crashes before it has a chance to complete additional tasks related to the disposition. Upon restart, the application may ask for initial data to regain its state and the delay introduced by the service_cleanup_delay will allow the restarted application to receive the information on the disposed instance and complete the interrupted tasks.

Compatibility

The value offered is considered compatible with the value requested if and only if the inequality offered kind >= requested kind evaluates to 'TRUE'. For the purposes of this inequality, the values of DURABILITY kind are considered ordered such that DDS.VOLATILE_DURABILITY_QOS < DDS.TRANSIENT_LOCAL_DURABILITY_QOS < DDS.TRANSIENT_DURABILITY_QOS < DDS.PERSISTENT_DURABILITY_QOS.

Kind: The kind of durability.

[default] DDS.VOLATILE_DURABILITY_QOS

Direct_Communication: <<ext>> Indicates whether or not a TRANSIENT or PERSISTENT DDS.DataReader should receive samples directly from a TRANSIENT or PERSISTENT DDS.DataWriter

When direct_communication is set to DDS.BOOLEAN_TRUE, a TRANSIENT or PERSISTENT DDS.DataReader will receive samples from both the original DDS.DataWriter configured with TRANSIENT or PERSISTENT durability and the DDS.DataWriter created by the persistence service. This peer-to-peer communication pattern provides low latency between end-points.

If the same sample is received from the original DDS.DataWriter and the persistence service, the middleware will discard the duplicate.

When direct_communication is set to DDS.BOOLEAN_FALSE, a TRANSIENT or PERSISTENT DDS.DataReader will only receive samples from the DDS.DataWriter created by the persistence service. This brokered communication pattern provides a way to guarantee eventual consistency.

[default] DDS.BOOLEAN_TRUE

Writer_Depth: <<ext>> Indicates the number of samples per instance that a durable DDS.DataWriter will send to a late-joining DDS.DataReader.

The default value, DDS.AUTO_WRITER_DEPTH, makes this parameter equal to the following:

• DDS.HistoryQosPolicy.depth if the history kind is DDS.KEEP_LAST_HISTORY_QOS.
• DDS.ResourceLimitsQosPolicy.max_samples_per_instance in the DDS.ResourceLimitsQosPolicy if the history kind is DDS.KEEP_ALL_HISTORY_QOS.

The `writer_depth` must be <= DDS.HistoryQosPolicy.depth.

`writer_depth` applies only to non-volatile DataWriters (those for which the kind is TRANSIENT_LOCAL, TRANSIENT, or PERSISTENT).

When DDS.BatchQosPolicy.enable is set to true, `writer_depth` acts as a minimum number of samples per instance that will be sent to late joiners, as opposed to the maximum. As long as a batch contains a single sample that falls within the `writer_depth` for the instance to which it belongs, then the entire batch will be sent. This means that batches sent to late-joining DataReaders may contain more samples per instance than is specified by the `writer_depth` QoS setting.

When a DataWriter responds to a TopicQuery, the samples that are evaluated against the TopicQuery filter are only those samples that fall within the `writer_depth`, not the DDS.HistoryQosPolicy.depth.

Setting `writer_depth` on the DataReader side will be ignored.

[default] DDS.AUTO_WRITER_DEPTH

Access scope determines the largest scope spanning the entities for which the order and coherency of changes can be preserved.

QoS:
DDS.PresentationQosPolicy

This QoS policy controls the extent to which changes to data instances can be made dependent on each other and also the kind of dependencies that can be propagated and maintained by dds. Specifically, this policy affects the application's ability to:

A DDS.DataReader expects a new sample updating the value of each instance at least once every period. That is, period specifies the maximum expected elapsed time between arriving data samples.

A DDS.DataWriter indicates that the application commits to write a new value (using the DDS.DataWriter) for each instance managed by the DDS.DataWriter at least once every period.

This QoS can be used during system integration to ensure that applications have been coded to meet design specifications.

It can also be used during run time to detect when systems are performing outside of design specifications. Receiving applications can take appropriate actions to prevent total system failure when data is not received in time. For topics on which data is not expected to be periodic, period should be set to an infinite value.

Entity:
DDS.Topic, DDS.DataReader, DDS.DataWriter

Status:
DDS.OFFERED_DEADLINE_MISSED_STATUS, DDS.REQUESTED_DEADLINE_MISSED_STATUS, DDS.OFFERED_INCOMPATIBLE_QOS_STATUS, DDS.REQUESTED_INCOMPATIBLE_QOS_STATUS

Properties:
"Rx0" = YES
"Changeable" = "YES"

Usage

This policy is useful for cases where a DDS.Topic is expected to have each instance updated periodically. On the publishing side this setting establishes a contract that the application must meet. On the subscribing side the setting establishes a minimum requirement for the remote publishers that are expected to supply the data values.

When RTI Connext 'matches' a DDS.DataWriter and a DDS.DataReader it checks whether the settings are compatible (i.e., offered deadline <= requested deadline); if they are not, the two entities are informed (via the DDS.Listener or DDS.Condition mechanism) of the incompatibility of the QoS settings and communication will not occur.

Assuming that the reader and writer ends have compatible settings, the fulfilment of this contract is monitored by RTI Connext and the application is informed of any violations by means of the proper DDS.Listener or DDS.Condition.

Compatibility

The value offered is considered compatible with the value requested if and only if the inequality offered period <= requested period holds.

Consistency

The setting of the DDSDeadlineQosModule policy must be set consistently with that of the DDSTimeBasedFilterQosModule.

For these two policies to be consistent the settings must be such that deadline period >= minimum_separation.

An attempt to set these policies in an inconsistent manner will result in DDS.RETCODE_INCONSISTENT_POLICY in Entity_set_qos, or the DDS.Entity will not be created.

For a DDS.DataReader, the DDSDeadlineQosModule policy and DDS.TimeBasedFilterQosPolicy may interact such that even though the DDS.DataWriter is writing samples fast enough to fulfill its commitment to its own deadline, the DDS.DataReader may see violations of its deadline. This happens because RTI Connext will drop any samples received within the DDS.TimeBasedFilterQosPolicy.minimum_separation. To avoid triggering the DDS.DataReader's deadline, even though the matched DDS.DataWriter is meeting its own deadline, set the two QoS parameters so that:

reader deadline >= reader minimum_separation + writer deadline

See DDS.TimeBasedFilterQosPolicy for more information about the interactions between deadlines and time-based filters.

See also: DDS.TimeBasedFilterQosPolicy

Period: Duration of the deadline period.

[default] DDS_DURATION_INFINITE

[range] [1 nanosec, 1 year] or DDS_DURATION_INFINITE, >= DDS.TimeBasedFilterQosPolicy.minimum_separation

This policy is a hint to a DDS implementation; it can be used to change how it processes and sends data that has low latency requirements. The DDS specification does not mandate whether or how this policy is used.

Entity:
DDS.Topic, DDS.DataReader, DDS.DataWriter

Status:
DDS.OFFERED_INCOMPATIBLE_QOS_STATUS, DDS.REQUESTED_INCOMPATIBLE_QOS_STATUS

Properties:
"Rx0" = YES
"Changeable" = "YES"

See also: DDS.PublishModeQosPolicy
See also: DDS.FlowController

Usage

This policy provides a means for the application to indicate to the middleware the urgency of the data communication. By having a non-zero duration, RTI Connext can optimize its internal operation.

RTI Connext uses it in conjunction with DDS.ASYNCHRONOUS_PUBLISH_MODE_QOS DDS.DataWriter instances associated with a DDS.EDF_FLOW_CONTROLLER_SCHED_POLICY DDS.FlowController only. Together with the time of write, DDS.LatencyBudgetQosPolicy.duration determines the deadline of each individual sample. RTI Connext uses this information to prioritize the sending of asynchronously published data; see DDS.AsynchronousPublisherQosPolicy.

Compatibility

The value offered is considered compatible with the value requested if and only if the inequality offered duration <= requested duration evaluates to 'TRUE'.

Duration: Duration of the maximum acceptable delay.

[default] 0 (meaning minimize the delay)

QoS:
DDS.OwnershipQosPolicy

Entity:
DDS.Topic, DDS.DataReader, DDS.DataWriter

Status:
DDS.OFFERED_INCOMPATIBLE_QOS_STATUS, DDS.REQUESTED_INCOMPATIBLE_QOS_STATUS

Properties:
"Rx0" = YES
"Changeable" = "UNTIL ENABLE"

See also: DDSOwnershipStrengthQosModule

Usage

Along with the DDSOwnershipStrengthQosModule, this QoS policy specifies if DDS.DataReader entities can receive updates to the same instance (identified by its key) from multiple DDS.DataWriter entities at the same time.

There are two kinds of ownership, selected by the setting of the kind: SHARED and EXCLUSIVE.

SHARED ownership

DDS.SHARED_OWNERSHIP_QOS indicates that RTI Connext does not enforce unique ownership for each instance. In this case, multiple writers can update the same data type instance. The subscriber to the DDS.Topic will be able to access modifications from all DDS.DataWriter objects, subject to the settings of other QoS that may filter particular samples (e.g. the DDSTimeBasedFilterQosModule or DDSHistoryQosModule policy). In any case, there is no "filtering" of modifications made based on the identity of the DDS.DataWriter that causes the modification.

EXCLUSIVE ownership

DDS.EXCLUSIVE_OWNERSHIP_QOS indicates that each instance of a data type can only be modified by one DDS.DataWriter. In other words, at any point in time, a single DDS.DataWriter owns each instance and is the only one whose modifications will be visible to the DDS.DataReader objects. The owner is determined by selecting the DDS.DataWriter with the highest value of the DDS.OwnershipStrengthQosPolicy.value that is currently alive, as defined by the DDSLivelinessQosModule policy, and has not violated its DDSDeadlineQosModule contract with regards to the data instance.

Ownership can therefore change as a result of:

This policy only applies if the DDSOwnershipQosModule policy is of kind DDS.EXCLUSIVE_OWNERSHIP_QOS.

Entity:
DDS.DataWriter

Properties:
"Rx0" = N/A
"Changeable" = "YES"

The value of the DDSOwnershipStrengthQosModule is used to determine the ownership of a data instance (identified by the key). The arbitration is performed by the DDS.DataReader.

See also: DDSOwnershipQosModule_usage_exclusive

Value: The strength value used to arbitrate among multiple writers.

[default] 0

[range] [0, 1 million]

QoS:
DDS.LivelinessQosPolicy

The liveliness status of a DDS.DataWriter is used to maintain instance ownership in combination with the setting of the DDSOwnershipQosModule policy. The application is also informed via DDS.Listener when an DDS.DataWriter is no longer alive.

A DDS.DataWriter commits to signalling its liveliness at intervals not to exceed the DDS.LivelinessQosPolicy.lease_duration configured on the DDS.DataWriter. The rate at which the DDS.DataWriter will signal its liveliness is defined by DDS.LivelinessQosPolicy.assertions_per_lease_duration.

The DDS.DataReader lease_duration specifies the maximum period at which matching DataWriters must have their liveliness asserted.

In addition, in the subscribing application Connext DDS uses an internal thread that wakes up at the period set by the DataReader's lease_duration to see if a DataWriter lease_duration has been violated.

Important: A DataReader will consider a DataWriter not alive if the DataWriter does not assert its liveliness within the DataWriter lease_duration not the DataReader lease_duration.

Listeners are used to notify a DDS.DataReader of loss of liveliness and DDS.DataWriter of violations to the liveliness contract. The on_liveliness_lost() callback is only called once, after the first time the lease_duration is exceeded (when the DDS.DataWriter first loses liveliness).

This QoS policy can be used during system integration to ensure that applications have been coded to meet design specifications. It can also be used during run time to detect when systems are performing outside of design specifications. Receiving applications can take appropriate actions in response to disconnected DataWriters.

Entity:
DDS.Topic, DDS.DataReader, DDS.DataWriter

Status:
DDS.LIVELINESS_LOST_STATUS, DDS.LivelinessLostStatus;
DDS.LIVELINESS_CHANGED_STATUS, DDS.LivelinessChangedStatus;
DDS.REQUESTED_INCOMPATIBLE_QOS_STATUS, DDS.OFFERED_INCOMPATIBLE_QOS_STATUS

Properties:
"Rx0" = YES
"Changeable" = "UNTIL ENABLE"

Usage

This policy controls the mechanism and parameters used by RTI Connext to ensure that particular DataWriters on the network are still alive. The liveliness can also affect the ownership of a particular instance, as determined by the DDSOwnershipQosModule policy.

This policy has several settings to support both data types that are updated periodically as well as those that are changed sporadically. It also allows customisation for different application requirements in terms of the kinds of failures that will be detected by the liveliness mechanism.

The DDS.AUTOMATIC_LIVELINESS_QOS liveliness setting is most appropriate for applications that only need to detect failures at the process-level, but not application-logic failures within a process. RTI Connext takes responsibility for renewing the leases at the required rates and thus, as long as the local process where a DDS.DomainParticipant is running and the link connecting it to remote participants remains connected, the entities within the DDS.DomainParticipant will be considered alive. This requires the lowest overhead.

The manual settings (DDS.MANUAL_BY_PARTICIPANT_LIVELINESS_QOS, DDS.MANUAL_BY_TOPIC_LIVELINESS_QOS) require the application on the publishing side to periodically assert the liveliness before the lease expires to indicate the corresponding DDS.Entity is still alive. The action can be explicit by calling the DDS.DataWriter.assert_liveliness operation or implicit by writing some data.

The two possible manual settings control the granularity at which the application must assert liveliness.

The filter states that the DDS.DataReader does not want to receive more than one value each minimum_separation, regardless of how fast the changes occur.

Entity:
DDS.DataReader

Properties:
"Rx0" = N/A
"Changeable" = "YES"

Usage

You can use this QoS policy to reduce the amount of data received by a DDS.DataReader. DDS.DataWriter entities may send data faster than needed by a DDS.DataReader. For example, a DDS.DataReader of sensor data that is displayed to a human operator in a GUI application does not need to receive data updates faster than a user can reasonably perceive changes in data values. This is often measured in tenths (0.1) of a second up to several seconds. However, a DDS.DataWriter of sensor information may have other DDS.DataReader entities that are processing the sensor information to control parts of the system and thus need new data updates in measures of hundredths (0.01) or thousandths (0.001) of a second.

With this QoS policy, different DDS.DataReader entities can set their own time-based filters, so that data published faster than the period set by a each DDS.DataReader will not be delivered to that DDS.DataReader.

The DDSTimeBasedFilterQosModule also applies to each instance separately; that is, the constraint is that the DDS.DataReader does not want to see more than one sample of each instance per minimum_separation period.

This QoS policy allows you to optimize resource usage (CPU and possibly network bandwidth) by only delivering the required amount of data to each DDS.DataReader, accommodating the fact that, for rapidly-changing data, different subscribers may have different requirements and constraints as to how frequently they need or can handle being notified of the most current values. As such, it can also be used to protect applications that are running on a heterogeneous network where some nodes are capable of generating data much faster than others can consume it.

For best effort data delivery, if the data type is unkeyed and the DDS.DataWriter has an infinite DDS.LivelinessQosPolicy.lease_duration, RTI Connext will only send as many packets to a DDS.DataReader as required by the TIME_BASED_FILTER, no matter how fast FooDataWriter.write is called.

For multicast data delivery to multiple DataReaders, the one with the lowest minimum_separation determines the DataWriter's send rate. For example, if a DDS.DataWriter sends over multicast to two DataReaders, one with minimum_separation of 2 seconds and one with minimum_separation of 1 second, the DataWriter will send every 1 second.

In configurations where RTI Connext must send all the data published by the DDS.DataWriter (for example, when the DDS.DataWriter is reliable, when the data type is keyed, or when the DDS.DataWriter has a finite DDS.LivelinessQosPolicy.lease_duration), only the data that passes the TIME_BASED_FILTER will be stored in the receive queue of the DDS.DataReader. Extra data will be accepted but dropped. Note that filtering is only applied on alive samples (that is, samples that have not been disposed/unregistered).

Consistency

However, it is important to be aware of certain edge cases that can occur when your publication rate, minimum separation, and deadline period align and that can cause missed deadlines that you may not expect. For example, suppose that you nominally publish samples every second but that this rate can vary somewhat over time. You declare a minimum separation of 1 second to filter out rapid updates and set a deadline of two seconds so that you will be aware if the rate falls too low. Even if your update rate never wavers, you can still miss deadlines! Here's why:

Suppose you publish the first sample at time t=0 seconds. You then publish your next sample at t=1 seconds. Depending on how your operating system schedules the time-based filter execution relative to the publication, this second sample may be filtered. You then publish your third sample at t=2 seconds, and depending on how your OS schedules this publication in relation to the deadline check, you could miss the deadline.

This scenario demonstrates a couple of rules of thumb:

This QoS policy is used to set string identifiers that are used for matching DataReaders and DataWriters for the same Topic.

A DDS.DataWriter within a DDS.Publisher only communicates with a DDS.DataReader in a DDS.Subscriber if (in addition to matching the DDS.Topic and having compatible QoS) the DDS.Publisher and DDS.Subscriber have a common partition name string.

Entity:
DDS.Publisher, DDS.Subscriber

Properties:
"Rx0" = NO
"Changeable" = "YES"

Usage

This policy allows the introduction of a logical partition concept inside the 'physical' partition induced by a domain.

Usually DataReaders and DataWriters are matched only by their topic (so that data are only sent by DataWriters to DataReaders for the same topic). The Partition QoS policy allows you to add one or more strings, "partitions", to a Publisher and/or Subscriber. If partitions are added, then a DataWriter and DataReader for the same topic are only considered matched if their Publishers and Subscribers have partitions in common (intersecting partitions).

Since the set of partitions for a publisher or subscriber can be dynamically changed, the Partition QoS policy 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.

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 a Publisher intersect with the partitions or wildcard patterns of a Subscriber, their DataWriters and DataReaders of the same topic are able to match; otherwise they are not.

These partition name patterns are regular expressions as defined by the POSIX fnmatch API (1003.2-1992 section B.6). Either DDS.Publisher or DDS.Subscriber 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 both at publisher as well as subscriber side, RTI Connext will not try to match two regular expressions (between publishers and subscribers).

Each publisher and subscriber must belong to at least one logical partition. A regular expression is not considered to be a logical partition. If a publisher or subscriber has not specify 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:

QoS:
DDS.ReliabilityQosPolicy

QoS:
DDS.ReliabilityQosPolicy

Entity:
DDS.Topic, DDS.DataReader, DDS.DataWriter

Status:
DDS.OFFERED_INCOMPATIBLE_QOS_STATUS, DDS.REQUESTED_INCOMPATIBLE_QOS_STATUS

Properties:
"Rx0" = YES
"Changeable" = "UNTIL ENABLE"

Usage

This policy indicates the level of reliability requested by a DDS.DataReader or offered by a DDS.DataWriter.

The reliability of a connection between a DataWriter and DataReader is entirely user configurable. It can be done on a per DataWriter/DataReader connection. A connection may be configured to be "best effort" which means that RTI Connext will not use any resources to monitor or guarantee that the data sent by a DataWriter is received by a DataReader.

For some use cases, such as the periodic update of sensor values to a GUI displaying the value to a person, DDS.BEST_EFFORT_RELIABILITY_QOS delivery is often good enough. It is certainly the fastest, most efficient, and least resource-intensive (CPU and network bandwidth) method of getting the newest/latest value for a topic from DataWriters to DataReaders. But there is no guarantee that the data sent will be received. It may be lost due to a variety of factors, including data loss by the physical transport such as wireless RF or even Ethernet.

However, there are data streams (topics) in which you want an absolute guarantee that all data sent by a DataWriter is received reliably by DataReaders. This means that RTI Connext must check whether or not data was received, and repair any data that was rejected by resending a copy of the data as many times as it takes for the DataReader to receive the data. RTI Connext uses a reliability protocol configured and tuned by these QoS policies: DDS.HistoryQosPolicy, DDS.DataWriterProtocolQosPolicy, DDS.DataReaderProtocolQosPolicy, and DDS.ResourceLimitsQosPolicy.

The Reliability QoS policy is simply a switch to turn on the reliability protocol for a DataWriter/DataReader connection. The level of reliability provided by RTI Connext is determined by the configuration of the aforementioned QoS policies.

You can configure RTI Connext to deliver all data in the order they were sent (also known as absolute or strict reliability). Or, as a tradeoff for less memory, CPU, and network usage, you can choose a reduced level of reliability where only the last N values are guaranteed to be delivered reliably to DataReaders (where N is user-configurable). In the reduced level of reliability, there are no guarantees that the data sent before the last N are received. Only the last N data packets are monitored and repaired if necessary.

These levels are ordered, DDS.BEST_EFFORT_RELIABILITY_QOS < DDS.RELIABLE_RELIABILITY_QOS. A DDS.DataWriter offering one level is implicitly offering all levels below.

Note: To send large data reliably, you will also need to set DDS.ASYNCHRONOUS_PUBLISH_MODE_QOS. Large in this context means that the data cannot be sent as a single packet by the transport (for example, data larger than 63K when using UDP/IP).

The setting of this policy has a dependency on the setting of the DDSResourceLimitsQosModule policy. In case the reliability kind is set to DDS.RELIABLE_RELIABILITY_QOS the write operation on the DDS.DataWriter may block if the modification would cause data to be lost or else cause one of the limits in specified in the DDSResourceLimitsQosModule to be exceeded. Under these circumstances, the DDSReliabilityQosModule max_blocking_time configures the maximum duration the write operation may block.

If the DDS.ReliabilityQosPolicy.kind is set to DDS.RELIABLE_RELIABILITY_QOS, data samples originating from a single DDS.DataWriter cannot be made available to the DDS.DataReader if there are previous data samples that have not been received yet due to a communication error. In other words, RTI Connext will repair the error and resend data samples as needed in order to reconstruct a correct snapshot of the DDS.DataWriter history before it is accessible by the DDS.DataReader.

If the DDS.ReliabilityQosPolicy.kind is set to DDS.BEST_EFFORT_RELIABILITY_QOS, the service will not re-transmit missing data samples. However, for data samples originating from any one DataWriter the service will ensure they are stored in the DDS.DataReader history in the same order they originated in the DDS.DataWriter. In other words, the DDS.DataReader may miss some data samples, but it will never see the value of a data object change from a newer value to an older value.

See also: DDS.HistoryQosPolicy
See also: DDS.ResourceLimitsQosPolicy

Compatibility

The value offered is considered compatible with the value requested if and only if:

QoS:
DDS.DestinationOrderQosPolicy

Entity:
DDS.Topic, DDS.DataReader, DDS.DataWriter

Status:
DDS.OFFERED_INCOMPATIBLE_QOS_STATUS, DDS.REQUESTED_INCOMPATIBLE_QOS_STATUS

Properties:
"Rx0" = YES
"Changeable" = "UNTIL ENABLE"

Usage

When multiple DataWriters send data for the same topic, the order in which data from different DataWriters are received by the applications of different DataReaders may be different. So different DataReaders may not receive the same "last" value when DataWriters stop sending data.

This QoS policy controls how each subscriber resolves the final value of a data instance that is written by multiple DDS.DataWriter entities (which may be associated with different DDS.Publisher entities) running on different nodes.

This QoS can be used to create systems that have the property of "eventual consistency." Thus intermediate states across multiple applications may be inconsistent, but when DataWriters stop sending changes to the same topic, all applications will end up having the same state.

This QoS policy can be set for both DataWriters and DataReaders.

For the DataReader:

The default setting, DDS.BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS, indicates that (assuming the DDSOwnershipStrengthQosModule policy allows it) the latest received value for the instance should be the one whose value is kept. That is, data will be delivered by a DDS.DataReader in the order in which it was received (which may lead to inconsistent final values).

For DDS.BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS, if the scope is set to DDS.INSTANCE_SCOPE_DESTINATIONORDER_QOS (default), within each instance, the sample's source timestamp shall be used to determine the most recent information. This is the only setting that, in the case of concurrent same-strength DataWriters updating the same instance, ensures that all DataReaders end up with the same final value for the instance. If a DataReader receives a sample for an instance with a source timestamp that is older than the last source timestamp received for the instance, the sample is dropped. The SAMPLE_REJECTED status or the SAMPLE_LOST status will not be updated.

If scope is set to DDS.TOPIC_SCOPE_DESTINATIONORDER_QOS, the ordering is enforced per topic across all instances.

In addition, a DataReader will accept a sample only if the source timestamp is no farther in the future from the reception timestamp than source_timestamp_tolerance. Otherwise, the DDS sample is dropped. The SAMPLE_REJECTED status or the SAMPLE_LOST status will not be updated.

For the DataWriter:

For the default setting, DDS.BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS, the DataWriter will not enforce source timestamp ordering when writing samples using the FooDataWriter.write_w_params or FooDataWriter.write_w_timestamp API. The source timestamp of a new sample can be older than the source timestamp of the previous samples.

When using DDS.BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS, If scope is set to DDS.INSTANCE_SCOPE_DESTINATIONORDER_QOS (default), when writing a sample, the sample's timestamp must not be older than the timestamp of the previously written DDS sample for the same instance. If, however, the timestamp is older than the timestamp of the previously written DDS sample---but the difference is less than the source_timestamp_tolerance---the DDS sample will use the previously written DDS sample's timestamp as its timestamp. Otherwise, if the difference is greater than the tolerance, the write will fail with retcode DDS.RETCODE_BAD_PARAMETER.

If scope is set to DDS.TOPIC_SCOPE_DESTINATIONORDER_QOS, a new sample timestamp must not be older than the timestamp of the previously written DDS sample, across all instances. (The ordering is enforced across all instances.)

Compatibility

The value offered is considered compatible with the value requested if and only if the inequality offered kind >= requested kind evaluates to 'TRUE'. For the purposes of this inequality, the values of DDS.DestinationOrderQosPolicy.kind are considered ordered such that DDS.BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS < DDS.BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS

Kind: Specifies the desired kind of destination order.

[default] DDS.BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS,

source_timestamp_tolerance: <<ext>> Allowed tolerance between source timestamps of consecutive samples.

When a DDS.DataWriter sets DDS.DestinationOrderQosPolicyKind to DDS.BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS, when writing a sample, its timestamp must not be less than the timestamp of the previously written sample. However, if it is less than the timestamp of the previously written sample but the difference is less than this tolerance, the sample will use the previously written sample's timestamp as its timestamp. Otherwise, if the difference is greater than this tolerance, the write will fail.

When a DDS.DataReader sets DDS.DestinationOrderQosPolicyKind to DDS.BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS, the DDS.DataReader will accept a sample only if the source timestamp is no farther in the future from the reception timestamp than this tolerance. Otherwise, the sample is dropped.

[default] 100 milliseconds for DDS.DataWriter, 30 seconds for DDS.DataReader \if CPP2_LANGUAGE_ONLY and when default-constructed\endif

QoS:
DDS.HistoryQosPolicy

This QoS policy specifies how much data must to stored by RTI Connext for a DDS.DataWriter or DDS.DataReader. It controls whether RTI Connext should deliver only the most recent value, attempt to deliver all intermediate values, or do something in between.

On the publishing side, this QoS policy controls the samples that should be maintained by the DDS.DataWriter on behalf of existing DDS.DataReader entities. The behavior with regards to a DDS.DataReader entities discovered after a sample is written is controlled by the DDSDurabilityQosModule policy.

On the subscribing side, this QoS policy controls the samples that should be maintained until the application "takes" them from dds.

Entity:
DDS.Topic, DDS.DataReader, DDS.DataWriter

Properties:
"Rx0" = NO
"Changeable" = "UNTIL ENABLE"

See also: DDS.ReliabilityQosPolicy
See also: DDS.HistoryQosPolicy

Usage

This policy controls the behavior of RTI Connext when the value of an instance changes before it is finally communicated to DDS.DataReader entities.

When a DDS.DataWriter sends data, or a DDS.DataReader receives data, the data sent or received is stored in a cache whose contents are controlled by this QoS policy. This QoS policy interacts with DDS.ReliabilityQosPolicy by controlling whether RTI Connext guarantees that all of the sent data is received (DDS.KEEP_ALL_HISTORY_QOS) or if only the last N data values sent are guaranteed to be received (DDS.KEEP_LAST_HISTORY_QOS)--this is a reduced level of reliability.

The amount of data that is sent to new DataReaders who have configured their DDS.DurabilityQosPolicy to receive previously published data is controlled by DDS.DurabilityQosPolicy.writer_depth, not by the History QoS policy.

Note that the History QoS policy does not control the physical sizes of the send and receive queues. The memory allocation for the queues is controlled by the DDS.ResourceLimitsQosPolicy.

If kind is DDS.KEEP_LAST_HISTORY_QOS (the default), then RTI Connext will only attempt to keep the latest values of the instance and discard the older ones. In this case, the value of depth regulates the maximum number of values (up to and including the most current one) RTI Connext will maintain and deliver until the samples are fully acknowledged. After N values have been sent or received, any new data will overwrite the oldest data in the queue. Thus the queue acts like a circular buffer of length N.

For keyed-data, there is different behavior on the publishing and subscribing sides associated with how invalid samples representing the disposal of or unregistration from an instance affect history.

On the publishing side, unregistering from or disposing of an instance creates an invalid sample that is accounted for in the history depth. This means that an invalid sample may replace a value that is currently being stored in the writer queue.

On the subscribing side, however, invalid samples do not count towards history depth and will not replace a value that is being stored in the reader queue.

On both the publishing and subscribing sides, there can only ever be one invalid sample per-instance and that one sample can be in different states depending on whether the instance has been disposed, unregistered, or both.

The default (and most common setting) for depth is 1, indicating that only the most recent value should be delivered.

If kind is DDS.KEEP_ALL_HISTORY_QOS, then RTI Connext will attempt to maintain and deliver all the values of the instance to existing subscribers. The resources that RTI Connext can use to keep this history are limited by the settings of the DDSResourceLimitsQosModule. If the limit is reached, then the behavior of RTI Connext will depend on the DDSReliabilityQosModule. If the Reliability kind is DDS.BEST_EFFORT_RELIABILITY_QOS, then the old values will be discarded. If Reliability kind is RELIABLE, then RTI Connext will block the DDS.DataWriter until it can deliver the necessary old values to all subscribers.

Consistency

This QoS policy's depth must be consistent with the DDSResourceLimitsQosModule max_samples_per_instance. For these two QoS to be consistent, they must verify that depth <= max_samples_per_instance.

See also: DDS.ResourceLimitsQosPolicy

Kind: Specifies the kind of history to be kept.

For DataWriters, the samples are only kept either until they are fully acknowledged by all matching DataReaders or until they are replaced or removed. Samples can be replaced or removed for a number of reasons, including but not limited to DDS.LifespanQosPolicy expiration, replacement because the DDS.HistoryQosPolicy.depth has been exceeded, or one of the DDS.ResourceLimitsQosPolicy settings has been exceeded.

[default] DDS.KEEP_LAST_HISTORY_QOS

Depth: Specifies the number of samples per instance to be kept, when the kind is DDS.KEEP_LAST_HISTORY_QOS

If a value other than 1 (the default) is specified, it should be consistent with the settings of the DDSResourceLimitsQosModule policy. That is:

depth <= DDS.ResourceLimitsQosPolicy.max_samples_per_instance

When the kind is DDS.KEEP_ALL_HISTORY_QOS, the depth has no effect. Its implied value is infinity (in practice limited by the settings of the DDSResourceLimitsQosModule policy).

When a DataWriter responds to a TopicQuery, the samples that are evaluated against the TopicQuery filter are only those samples that fall within the DDS.DurabilityQosPolicy.writer_depth, not this depth.

[default] 1

[range] [1,100 million], <= DDS.ResourceLimitsQosPolicy.max_samples_per_instance

Entity:
DDS.Topic, DDS.DataWriter

Properties:
"Rx0" = NO
"Changeable" = "UNTIL ENABLE"

See also: DDSDurabilityQosModule
See also: DDSHistoryQosModule
See also: DDSResourceLimitsQosModule

Usage

When a DataWriter's DDS.DurabilityQosPolicy.kind is DDS.PERSISTENT_DURABILITY_QOS or DDS.TRANSIENT_DURABILITY_QOS, an external service, the RTI Persistence Service, is used to store and possibly forward the data sent by the DDS.DataWriter to DDS.DataReader objects that are created after the data was initially sent.

This QoS policy is used to configure certain parameters of the Persistence Service when it operates on the behalf of the DDS.DataWriter, such as how much data to store. For example, it configures the DDSDurabilityQosModule, DDSHistoryQosModule, and the DDSResourceLimitsQosModule used by the fictitious DataReader and DataWriter used by the Persistence Service. Note, however, that the Persistence Service itself may be configured to ignore these values and instead use values from its own configuration file.

Service_Cleanup_Delay: Controls when the service is able to remove all information regarding a data instances.

When the service cleanup delay is set to 0, disposed instances will be completely removed from the service. Only values of 0 and DDS_DURATION_INFINITE are currently supported.

[default] 0

History_Kind: The kind of history to apply in recouping durable data.

[default] DDS.KEEP_LAST_HISTORY_QOS

History_Depth: Setting to use for the DDS.DurabilityQosPolicy.writer_depth when recouping durable data.

If the DDS.HistoryQosPolicy.depth is set to a value lower than this value, DDS.HistoryQosPolicy.depth will be set equal to the value of this field.

[default] DDS.AUTO_WRITER_DEPTH (1)

Max_Samples: Part of resource limits QoS policy to apply when feeding a late joiner.

[default] DDS.LENGTH_UNLIMITED

Max_Instances: Part of resource limits QoS policy to apply when feeding a late joiner.

[default] DDS.LENGTH_UNLIMITED

Max_Samples_Per_Instance: Part of resource limits QoS policy to apply when feeding a late joiner.

[default] DDS.LENGTH_UNLIMITED

Entity:
DDS.Topic, DDS.DataReader, DDS.DataWriter

Status:
DDS.SAMPLE_REJECTED_STATUS, DDS.SampleRejectedStatus

Properties:
"Rx0" = NO
"Changeable" = "UNTIL ENABLE"

Usage

This policy controls the resources that RTI Connext can use to meet the requirements imposed by the application and other QoS settings.

For the reliability protocol (and DDS.DurabilityQosPolicy), this QoS policy determines the actual maximum queue size when the DDS.HistoryQosPolicy is set to DDS.KEEP_ALL_HISTORY_QOS.

In general, this QoS policy is used to limit the amount of system memory that RTI Connext can allocate. For embedded real-time systems and safety-critical systems, pre-determination of maximum memory usage is often required. In addition, dynamic memory allocation could introduce non-deterministic latencies in time-critical paths.

This QoS policy can be set such that an entity does not dynamically allocate any more memory after its initialization phase.

If DDS.DataWriter objects are communicating samples faster than they are ultimately taken by the DDS.DataReader objects, the middleware will eventually hit against some of the QoS-imposed resource limits. Note that this may occur when just a single DDS.DataReader cannot keep up with its corresponding DDS.DataWriter. The behavior in this case depends on the setting for the DDSReliabilityQosModule. If reliability is DDS.BEST_EFFORT_RELIABILITY_QOS, then RTI Connext is allowed to drop samples. If the reliability is DDS.RELIABLE_RELIABILITY_QOS, RTI Connext will block the DDS.DataWriter or discard the sample at the DDS.DataReader in order not to lose existing samples.

The constant DDS.LENGTH_UNLIMITED may be used to indicate the absence of a particular limit. For example setting DDS.ResourceLimitsQosPolicy.max_samples_per_instance to DDS.LENGTH_UNLIMITED will cause RTI Connext not to enforce this particular limit.

If these resource limits are not set sufficiently, under certain circumstances the DDS.DataWriter may block on a write() call even though the DDS.HistoryQosPolicy is DDS.KEEP_LAST_HISTORY_QOS. To guarantee the writer does not block for DDS.KEEP_LAST_HISTORY_QOS, make sure the resource limits are set such that:

max_samples >= max_instances * max_samples_per_instance

See also: DDS.ReliabilityQosPolicy
See also: DDS.HistoryQosPolicy

Consistency

The setting of DDS.ResourceLimitsQosPolicy.max_samples must be consistent with DDS.ResourceLimitsQosPolicy.max_samples_per_instance. For these two values to be consistent, it must be true that DDS.ResourceLimitsQosPolicy.max_samples >= DDS.ResourceLimitsQosPolicy.max_samples_per_instance. As described above, this limit will not be enforced if DDS.ResourceLimitsQosPolicy.max_samples_per_instance is set to DDS.LENGTH_UNLIMITED.

The setting of DDSResourceLimitsQosModule max_samples_per_instance must be consistent with the DDSHistoryQosModule depth. For these two QoS to be consistent, it must be true that depth <= max_samples_per_instance.

See also: DDS.HistoryQosPolicy

Max_Samples: Represents the maximum samples the middleware can store for any one DDS.DataWriter (or DDS.DataReader).

Specifies the maximum number of data samples a DDS.DataWriter (or DDS.DataReader) can manage across all the instances associated with it.

For unkeyed types, this value has to be equal to max_samples_per_instance if max_samples_per_instance is not equal to DDS.LENGTH_UNLIMITED.

When batching is enabled, the maximum number of data samples a DDS.DataWriter can manage will also be limited by DDS.DataWriterResourceLimitsQosPolicy.max_batches.

[default] DDS.LENGTH_UNLIMITED

[range] [1, 100 million] or DDS.LENGTH_UNLIMITED, >= initial_samples, >= max_samples_per_instance, >= DDS.DataReaderResourceLimitsQosPolicy.max_samples_per_remote_writer or >= DDS.RtpsReliableWriterProtocol_t.heartbeats_per_max_samples

For DDS.DataWriterQos max_samples >= DDS.RtpsReliableWriterProtocol_t.heartbeats_per_max_samples in DDS.DataWriterProtocolQosPolicy.rtps_reliable_writer if batching is disabled.

Max_Instances: Represents the maximum number of instances a DDS.DataWriter (or DDS.DataReader) can manage.

[default] DDS.LENGTH_UNLIMITED

[range] [1, 1 million] or DDS.LENGTH_UNLIMITED, >= initial_instances

Max_Samples_Per_Instance: Represents the maximum number of samples of any one instance a DDS.DataWriter (or DDS.DataReader) can manage.

While an unkeyed type is logically considered as a single instance, for unkeyed types this value has to be equal to max_samples or DDS.LENGTH_UNLIMITED.

[default] DDS.LENGTH_UNLIMITED

[range] [1, 100 million] or DDS.LENGTH_UNLIMITED, <= max_samples or DDS.LENGTH_UNLIMITED, >= DDS.HistoryQosPolicy.depth

Initial_Samples: <<ext>> Represents the initial samples the middleware will store for any one DDS.DataWriter (or DDS.DataReader).

Specifies the initial number of data samples a DDS.DataWriter (or DDS.DataReader) will manage across all the instances associated with it.

[default] 32

[range] [1,100 million], <= max_samples

Initial_Instances: <<ext>> Represents the initial number of instances a DDS.DataWriter (or DDS.DataReader) will manage.

[default] 32

[range] [1,1 million], <= max_instances

Instance_Hash_Buckets: <<ext>> Number of hash buckets for instances.

The instance hash table facilitates instance lookup. A higher number of buckets decreases instance lookup time but increases the memory usage.

[default] 1 [range] [1,1 million]

The Transport Priority QoS policy is optional and only supported on certain OSs and transports. It allows you to specify on a per-DataWriter or DataReader basis that the data sent by that endpoint is of a different priority.

The DDS specification does not indicate how a DDS implementation should treat data of different priorities. It is often difficult or impossible for DDS implementations to treat data of higher priority differently than data of lower priority, especially when data is being sent (delivered to a physical transport) directly by the thread that called FooDataWriter.write. Also, many physical network transports themselves do not have a end-user controllable level of data packet priority.

Entity:
DDS.DataWriter, DDS.DataReader, DDS.Topic

Properties:
"Rx0" = N/A
"Changeable" = "NO"

Usage

In dds, for the IP-based transports (UDPv4, UDPv6, Real-Time WAN, and TCP), the value set in the Transport Priority QoS policy can be used to set the differentiated services field (DS field) bits of the IPv4 and IPv6 headers for datagrams sent by a DDS.DataWriter or DDS.DataReader. It is platform-dependent on how and whether setting the DS field has an effect. Some platforms may require external permissions in order to set the DS field.

The transport priority value is not provided as is to the transports, but transformed according to the following fields: transport_priority_mask (for example, see NDDS_Transport_UDPv4_Property_t.transport_priority_mask), transport_priority_mapping_low (for example, see NDDS_Transport_UDPv4_Property_t.transport_priority_mapping_low), and transport_priority_mapping_high (for example, see NDDS_Transport_UDPv4_Property_t.transport_priority_mapping_high). If you want the priority value to be exactly equal to the DS value, then the only change you need to make is to set transport_priority_mask to 0xff (and keep the transport_priority_mapping_low and transport_priority_mapping_high defaults).

It is incorrect to assume that using the Transport Priority QoS policy will have any effect at all on the end-to-end delivery of data from a DDS.DataWriter and a DDS.DataReader. All network elements, including switches and routers, must have the capability and be enabled to actually use the DS field to treat higher priority packets differently. Thus the ability to use the Transport Priority QoS policy must be designed and configured at a system level; just turning it on in an application may have no effect at all at a transport level.

For additional details on how to set the DS field in IP-based transports, see the "TRANSPORT_PRIORITY QosPolicy" section of the User's Manual .

Value: This policy is a hint to the infrastructure as to how to set the priority of the underlying transport used to send the data.

You may choose any value within the range of a 32-bit signed integer; higher values indicate higher priority. However, any further interpretation of this policy is specific to a particular transport and a particular DDS implementation. For example, a particular transport is permitted to treat a range of priority values as equivalent to one another.

[default] 0

Each data sample written by the DDS.DataWriter has an associated expiration time beyond which the data should not be delivered to any application. Once the sample expires, the data will be removed from the DDS.DataReader caches as well as from the transient and persistent information caches.

The expiration time of each sample from the DDS.DataWriter's cache is computed by adding the duration specified by this QoS policy to the time when the sample is added to the DDS.DataWriter's cache. This timestamp is not necessarily equal to the sample's source timestamp that can be provided by the user using the FooDataWriter.write_w_timestamp or FooDataWriter.write_w_params API.

The expiration time of each sample from the DDS.DataReader's cache is computed by adding the duration to the reception timestamp.

See also: FooDataWriter.write
See also: FooDataWriter.write_w_timestamp

Entity:
DDS.Topic, DDS.DataWriter

Properties:
"Rx0" = N/A
"Changeable" = "YES"

Usage

The Lifespan QoS policy can be used to control how much data is stored by dds. Even if it is configured to store "all" of the data sent or received for a topic (see DDS.HistoryQosPolicy), the total amount of data it stores may be limited by this QoS policy.

You may also use this QoS policy to ensure that applications do not receive or act on data, commands or messages that are too old and have 'expired.'

To avoid inconsistencies, multiple writers of the same instance should have the same lifespan.

See also: DDS.SampleInfo.source_timestamp
See also: DDS.SampleInfo.reception_timestamp

Duration: Maximum duration for the data's validity.

[default] DDS_DURATION_INFINITE

[range] [1 nanosec, 1 year] or DDS_DURATION_INFINITE

Entity:
DDS.DataWriter

Properties:
"Rx0" = N/A
"Changeable" = "YES"

Usage

This policy determines how the DDS.DataWriter acts with regards to the lifecycle of the data instances it manages (data instances that have been either explicitly registered with the DDS.DataWriter or implicitly registered by directly writing the data).

You may use FooDataWriter.unregister_instance to indicate that the DDS.DataWriter no longer wants to send data for a DDS.Topic.

The behavior controlled by this QoS policy applies on a per instance (key) basis for keyed Topics, so that when a DDS.DataWriter unregisters an instance, RTI Connext can automatically also dispose that instance. This is the default behavior.

In many cases where the ownership of a Topic is shared (see DDS.OwnershipQosPolicy), DataWriters may want to relinquish their ownership of a particular instance of the Topic to allow other DataWriters to send updates for the value of that instance regardless of Ownership Strength. In that case, you may only want a DataWriter to unregister an instance without disposing the instance. Disposing an instance is a statement that an instance no longer exists. User applications may be coded to trigger on the disposal of instances, thus the ability to unregister without disposing may be useful to properly maintain the semantic of disposal.

Autodispose_Unregistered_Instances: Boolean flag that controls the behavior when the DDS.DataWriter unregisters an instance by means of the unregister operations.

• DDS.BOOLEAN_TRUE
  The DDS.DataWriter will dispose of the instance each time it is unregistered. The behavior is identical to explicitly calling one of the dispose operations on the instance prior to calling the unregister operation.
• DDS.BOOLEAN_FALSE (default)
  The DDS.DataWriter will not dispose of the instance. The application can still call one of the dispose operations prior to unregistering the instance and dispose of the instance that way.

[default] DDS.BOOLEAN_FALSE

Autopurge_Unregistered_Instances_Delay: <<ext>> Maximum duration for which the DDS.DataWriter will maintain information regarding an instance once it has unregistered the instance.

Determines how long the DDS.DataWriter will maintain information regarding an instance that has been unregistered. By default, the DDS.DataWriter resources associated with an instance (e.g., the space needed to remember the Instance Key or KeyHash) are released lazily. This means the resources are only reclaimed when the space is needed for another instance because DDS.ResourceLimitsQosPolicy.max_instances is exceeded. This behavior can be changed by setting autopurge_unregistered_instances_delay to a value other than DDS_DURATION_INFINITE.

After this time elapses, the DDS.DataWriter will purge all internal information regarding the instance, including historical samples, even if DDS.ResourceLimitsQosPolicy.max_instances has not been reached.

The purging of unregistered instances can be done based on the source timestamp of the unregister sample or the time where the unregister sample was added to the DataWriter queue by setting the following property to 1 or 0 respectively (default: 0): dds.data_writer.history.source_timestamp_based_autopurge_instances_delay.

For durable writer history, autopurge_unregistered_instances_delay supports only the DDS_DURATION_INFINITE value.

[default] DDS_DURATION_INFINITE (disabled) for all DDS.DataWriter except for the built-in discovery DataWriters DDS_DURATION_ZERO for built-in discovery DataWriters (see DDS.DiscoveryConfigQosPolicy.publication_writer_data_lifecycle and DDS.DiscoveryConfigQosPolicy.subscription_writer_data_lifecycle).

[range] [0, 1 year] or DDS_DURATION_INFINITE

Autopurge_Disposed_Instances_Delay: <<ext>> Maximum duration for which the DDS.DataWriter will maintain information regarding an instance once it has disposed the instance.

Determines how long the DDS.DataWriter will maintain information regarding an instance that has been disposed of. By default, disposing of an instance does not make it eligible to be purged. By setting autopurge_disposed_instances_delay to a value other than DDS_DURATION_INFINITE, the DataWriter will delete the resources associated with an instance (including historical samples) once the time has elapsed and all matching DataReaders have acknowledged all the samples for this instance including the dispose sample.

The purging of disposed instances can be done based on the source timestamp of the dispose sample or the time when the dispose sample was added to the DataWriter queue by setting the following property to 1 or 0 respectively (default: 0): dds.data_writer.history.source_timestamp_based_autopurge_instances_delay.

This QoS value is supported with durable DataWriter queues only for DDS_DURATION_ZERO and DDS_DURATION_INFINITE values (finite values are not supported).

[default] DDS_DURATION_INFINITE (disabled)

[range] [0, 1 year] or DDS_DURATION_INFINITE

When a DataReader receives data, it is stored in a receive queue for the DataReader. The user application may either take the data from the queue or leave it there.

This QoS policy controls whether or not RTI Connext will automatically remove data from the receive queue (so that user applications cannot access it afterwards) when it detects that there are no more DataWriters alive for that data. It specifies how long a DDS.DataReader must retain information regarding instances that have the instance_state DDS.NOT_ALIVE_NO_WRITERS_INSTANCE_STATE.

Note: This policy is not concerned with keeping reliable reader state or discovery information.

The DDS.DataReader internally maintains the samples that have not been "taken" by the application, subject to the constraints imposed by other QoS policies such as DDS.HistoryQosPolicy and DDS.ResourceLimitsQosPolicy.

The DDS.DataReader also maintains information regarding the identity, view_state and instance_state of data instances even after all samples have been taken. This is needed to properly compute the states when future samples arrive.

Under normal circumstances the DDS.DataReader can only reclaim all resources for instances for which there are no writers and for which all samples have been 'taken'. The last sample the DDS.DataReader will have taken for that instance will have an instance_state of either DDS.NOT_ALIVE_NO_WRITERS_INSTANCE_STATE or DDS.NOT_ALIVE_DISPOSED_INSTANCE_STATE depending on whether or not the last writer that had ownership of the instance disposed it.

In the absence of DDSReaderDataLifecycleQosModule, this behavior could cause problems if the application forgets to take those samples. "Untaken" samples will prevent the DDS.DataReader from reclaiming the resources and they would remain in the DDS.DataReader indefinitely.

A DataReader can also reclaim all resources for instances that have an instance state of DDS.NOT_ALIVE_DISPOSED_INSTANCE_STATE and for which all DDS samples have been 'taken'. DataReaders will only reclaim resources in this situation when the autopurge_disposed_instances_delay has been set to zero.

For keyed Topics, the consideration of removing data samples from the receive queue is done on a per instance (key) basis. Thus when RTI Connext detects that there are no longer DataWriters alive for a certain key value of a Topic (an instance of the Topic), it can be configured to remove all data samples for that instance (key).

Entity:
DDS.DataReader

Properties:
"Rx0" = N/A
"Changeable" = "YES"

Autopurge_Nowriter_Samples_Delay: Minimum duration for which the DDS.DataReader will maintain information regarding an instance once its instance_state becomes DDS.NOT_ALIVE_NO_WRITERS_INSTANCE_STATE.

At some point after this time elapses, the DDS.DataReader will purge all internal information regarding the instance, any "untaken" samples will also be dropped.

[default] DDS_DURATION_INFINITE

[range] [1 nanosec, 1 year] or DDS_DURATION_INFINITE

Autopurge_Disposed_Samples_Delay: Minimum duration for which the DDS.DataReader will maintain samples for an instance once its instance_state becomes DDS.NOT_ALIVE_DISPOSED_INSTANCE_STATE.

After this time elapses, the DDS.DataReader will purge all samples for the instance even if they have not been read by the application. This purge is done lazily when space is needed for other samples or instances.

[default] DDS_DURATION_INFINITE

[range] [1 nanosec, 1 year] or DDS_DURATION_INFINITE

Autopurge_Disposed_Instances_Delay: <<ext>> Minimum duration for which the DDS.DataReader will maintain information about a received instance once its instance_state becomes DDS.NOT_ALIVE_DISPOSED_INSTANCE_STATE and there are no samples for the instance in the DataReader queue.

After this time elapses, when the last sample for the disposed instance is taken, the DDS.DataReader will keep only the minimum state about the instance.

If you do not want to keep this minimum state after the delay period, also set keep_minimum_state_for_instances to FALSE in DDS.DataReaderResourceLimitsQosPolicy.

The only currently supported values are DDS_DURATION_ZERO and DDS_DURATION_INFINITE. A value of DDS_DURATION_ZERO will purge an instance's state immediately after the instance state transitions to DDS.NOT_ALIVE_DISPOSED_INSTANCE_STATE, as long as all samples, including the dispose sample, associated with that instance have been 'taken'.

[default] DDS_DURATION_INFINITE

Autopurge_Disposed_Instances_Delay: <<ext>> Minimum duration for which the DDS.DataReader will maintain information about a received instance once its instance_state becomes DDS.NOT_ALIVE_NO_WRITERS_INSTANCE_STATE and there are no samples for the instance in the DataReader queue.

An instance will transition to the DDS.NOT_ALIVE_NO_WRITERS_INSTANCE_STATE instance_state when all known writers for the instance have either lost liveliness or have unregistered themselves from the instance. After this time elapses, when the last sample for the instance without writers is taken, the DDS.DataReader will keep only the minimum state about the instance.

If you do not want to keep this minimum state after the delay period, also set keep_minimum_state_for_instances to FALSE in DDS.DataReaderResourceLimitsQosPolicy.

The only currently supported values are DDS_DURATION_ZERO and DDS_DURATION_INFINITE. A value of DDS_DURATION_ZERO will purge an instance's state immediately after the instance state transitions to DDS.NOT_ALIVE_NO_WRITERS_INSTANCE_STATE, as long as all samples, including the no_writers sample, associated with that instance have been 'taken'.

[default] DDS_DURATION_ZERO

Entity:
DDS.DomainParticipantFactory, DDS.DomainParticipant, DDS.Publisher, DDS.Subscriber

Properties:
"Rx0" = NO
"Changeable" = "YES"

Usage

RTI Connext uses a factory design pattern for creating DDS Entities. That is, a parent entity must be used to create child entities. DomainParticipants create Topics, Publishers and Subscribers. Publishers create DataWriters. Subscribers create DataReaders.

By default, a child object is enabled upon creation (initialized and may be actively used). With this QoS policy, a child object can be created in a disabled state. A disabled entity is only partially initialized and cannot be used until the entity is enabled. Note: an entity can only be enabled; it cannot be disabled after it has been enabled.

This QoS policy is useful to synchronize the initialization of DDS Entities. For example, when a DDS.DataReader is created in an enabled state, its existence is immediately propagated for discovery and the DDS.DataReader object's listener called as soon as data is received. The initialization process for an application may extend beyond the creation of the DDS.DataReader, and thus, it may not be desireable for the DDS.DataReader to start to receive or process any data until the initialization process is complete. So by creating readers in a disabled state, your application can make sure that no data is received until the rest of the application initialization is complete, and at that time, enable the them.

Note: if an entity is disabled, then all of the child entities it creates will be disabled too, regardless of the setting of this QoS policy. However, enabling a disabled entity will enable all of its children if this QoS policy is set to automatically enable children entities.

This policy is mutable. A change in the policy affects only the entities created after the change, not any previously created entities.

Autoenable_Created_Entities: Specifies whether the entity acting as a factory automatically enables the instances it creates.

The setting of autoenable_created_entities to DDS.BOOLEAN_TRUE indicates that the factory create_<entity> operation(s) will automatically invoke the DDS.Entity.enable operation each time a new DDS.Entity is created. Therefore, the DDS.Entity returned by create_<entity> will already be enabled. A setting of DDS.BOOLEAN_FALSE indicates that the DDS.Entity will not be automatically enabled. Your application will need to call DDS.Entity.enable itself.

The default setting of autoenable_created_entities = DDS.BOOLEAN_TRUE means that, by default, it is not necessary to explicitly call DDS.Entity.enable on newly created entities.

[default] DDS.BOOLEAN_TRUE

QoS:
DDS.DomainParticipantResourceLimitsQosPolicy

Initial_Count: The initial count of resources.