You are here: Part 2: Core Concepts > Receiving Data > DataReader QosPolicies > DATA_READER_RESOURCE_LIMITS QosPolicy (DDS Extension)

DATA_READER_RESOURCE_LIMITS QosPolicy (DDS Extension)

The DATA_READER_RESOURCE_LIMITS QosPolicy extends your control over the memory allocated by Connext DDS for DataReaders beyond what is offered by the RESOURCE_LIMITS QosPolicy. RESOURCE_LIMITS controls memory allocation with respect to the DataReader itself: the number of DDS samples that it can store in the receive queue and the number of instances that it can manage simultaneously. DATA_READER_RESOURCE_LIMITS controls memory allocation on a per matched-DataWriter basis. The two are orthogonal.

This policy includes the members in . For defaults and valid ranges, please refer to the API Reference HTML documentation.

DDS_DataReaderResourceLimitsQosPolicy

Type

Field Name

Description

DDS_
Long

max_remote_writers

Maximum number of DataWriters from which a DataReader may receive DDS data samples, among all instances.

For unkeyed Topics: max_remote_writers must = max_remote_writers_per_instance

max_remote_writers_
per_instance

Maximum number of DataWriters from which a DataReader may receive DDS data samples for a single instance.

For unkeyed Topics: max_remote_writers must = max_remote_writers_per_instance

max_samples_
per_remote_writer

Maximum number of DDS samples received out-of-order that a DataReader can store from a single reliable DataWriter.

max_samples_per_remote_writer must be <= RESOURCE_LIMITS::max_samples

max_infos

Maximum number of DDS_SampleInfo structures that a DataReader can allocate.

max_infos must be >= RESOURCE_LIMITS::max_samples

initial_remote_writers

Initial number of DataWriters from which a DataReader may receive DDS data samples, including all instances.

For unkeyed Topics: initial_remote_writers must = initial_remote_writers_per_instance

initial_remote_
writers_per_instance

Initial number of DataWriters from which a DataReader may receive DDS data samples for a single instance.

For unkeyed Topics: initial_remote_writers must = initial_remote_writers_per_instance

initial_infos

Initial number of DDS_SampleInfo structures that a DataReader will allocate.

initial_outstanding_
reads

Initial number of times in which memory can be concurrently loaned via read/take calls without being returned with return_loan().

max_outstanding_
reads

Maximum number of times in which memory can be concurrently loaned via read/take calls without being returned with return_loan().

max_samples_per_
read

Maximum number of DDS samples that can be read/taken on a DataReader.

DDS_
Boolean

disable_fragmentation_
support

Determines whether the DataReader can receive fragmented DDS samples.

When fragmentation support is not needed, disabling fragmentation support will save some memory resources.

DDS_
Long

max_fragmented_
samples

The maximum number of DDS samples for which the DataReader may store fragments at a given point in time.

At any given time, a DataReader may store fragments for up to max_fragmented_samples DDS samples while waiting for the remaining fragments. These DDS samples need not have consecutive sequence numbers and may have been sent by different DataWriters. Once all fragments of a DDS sample have been received, the DDS sample is treated as a regular DDS sample and becomes subject to standard QoS settings, such as max_samples. Connext DDS will drop fragments if the max_fragmented_samples limit has been reached.

For best-effort communication, Connext DDS will accept a fragment for a new DDS sample, but drop the oldest fragmented DDS sample from the same remote writer.

For reliable communication, Connext DDS will drop fragments for any new DDS samples until all fragments for at least one older DDS sample from that writer have been received.

Only applies if disable_fragmentation_support is FALSE.

initial_fragmented_
samples

The initial number of DDS samples for which a DataReader may store fragments.

Only applies if disable_fragmentation_support is FALSE.

max_fragmented_
samples_per_remote_
writer

The maximum number of DDS samples per remote writer for which a DataReader may store fragments. This is a logical limit, so a single remote writer cannot consume all available resources.

Only applies if disable_fragmentation_support is FALSE.

max_fragments_per_
sample

Maximum number of fragments for a single DDS sample.

Only applies if disable_fragmentation_support is FALSE.

DDS_
Boolean

dynamically_allocate_
fragmented_samples

By default, the middleware does not allocate memory upfront, but instead allocates memory from the heap upon receiving the first fragment of a new sample. The amount of memory allocated equals the amount of memory needed to store all fragments in the sample. Once all fragments of a sample have been received, the sample is deserialized and stored in the regular receive queue. At that time, the dynamically allocated memory is freed again.

This QoS setting is useful for large, but variable-sized data types where up-front memory allocation for multiple samples based on the maximum possible sample size may be expensive. The main disadvantage of not pre-allocating memory is that one can no longer guarantee the middleware will have sufficient resources at run-time.

If dynamically_allocate_fragmented_samples is FALSE, the middleware will allocate memory up-front for storing fragments for up to initial_fragmented_samples samples. This memory may grow up to max_fragmented_samples if needed.

Only applies if disable_fragmentation_support is FALSE.

DDS_
Long

max_total_instances

Maximum number of instances for which a DataReader will keep state.

See max_total_instances and max_instances

DDS_
Long

max_remote_virtual_
writers

The maximum number of virtual writers (identified by a virtual GUID) from which a DataReader may read, including all instances.

When the Subscriber’s access_scope is GROUP, this value determines the maximum number of DataWriter groups supported by the Subscriber. Since the Subscriber may contain more than one DataReader, only the setting of the first applies.

DDS_
Long

initial_remote_virtual_
writers

The initial number of virtual writers from which a DataReader may read, including all instances.

DDS_
Long

max_remote_virtual_
writers_per_instance

Maximum number of virtual remote writers that can be associated with an instance.

For unkeyed types, this value is ignored.

The features of Durable Reader State and MultiChannel DataWriters, as well as Persistence Service1Persistence Service is included with the Connext DDS Professional, Evaluation, and Basic package types. It saves DDS data samples so they can be delivered to subscribing applications that join the system at a later time (see Introduction to RTI Persistence Service)., require Connext DDS to keep some internal state per virtual writer and instance that is used to filter duplicate DDS samples. These duplicate DDS samples could be coming from different DataWriter channels or from multiple executions of Persistence Service.

Once an association between a remote virtual writer and an instance is established, it is permanent—it will not disappear even if the physical writer incarnating the virtual writer is destroyed.

If max_remote_virtual_writers_per_instance is exceeded for an instance, Connext DDS will not associate this instance with new virtual writers. Duplicate DDS samples coming from these virtual writers will not be filtered on the reader.

If you are not using Durable Reader State, MultiChannel DataWriters or Persistence Service, you can set this property to 1 to optimize resources.

For additional information about the virtual writers see Mechanisms for Achieving Information Durability and Persistence.

DDS_
Long

initial_remote_virtual_
writers_per_instance

Initial number of virtual remote writers per instance.

For unkeyed types, this value is ignored.

DDS_
Long

max_remote_writers_
per_sample

Maximum number of remote writers that are allowed to write the same DDS sample.

One scenario in which two DataWriters may write the same DDS sample is when using Persistence Service. The DataReader may receive the same DDS sample from the original DataWriter and from an Persistence Service DataWriter.

DDS_
Long

max_query_condition_
filters

This value determines the maximum number of unique query condition content filters that a reader may create.

Each query condition content filter is comprised of both its query_expression and query_parameters. Two query conditions that have the same query_expression will require unique query condition filters if their query_parameters differ. Query conditions that differ only in their state masks will share the same query condition filter.

DDS_
Long

max_app_ack_response_
length

Maximum length of application-level acknowledgment response data.

The maximum length of response data in an application-level acknowledgment.

When set to zero, no response data is sent with application-level acknowledgments.

DDS_Boolean

keep_minimum_state_for_instances

Determines whether the DataReader keeps a minimum instance state for up to max_total_instances. The minimum state is useful for filtering samples in certain scenarios. See max_total_instances and max_instances

DataReaders must allocate internal structures to handle: the maximum number of DataWriters that may connect to it; whether or not a DataReader handles data fragmentation and how many data fragments that it may handle (for DDS data samples larger than the MTU of the underlying network transport); how many simultaneous outstanding loans of internal memory holding DDS data samples can be provided to user code; as well as others.

Most of these internal structures start at an initial size and, by default, will grow as needed by dynamically allocating additional memory. You may set fixed, maximum sizes for these internal structures if you want to bound the amount of memory that can be used by a DataReader. Setting the initial size to the maximum size will prevent Connext DDS from dynamically allocating any memory after the DataReader is created.

This policy also controls how the allocated internal data structure may be used. For example, DataReaders need data structures to keep track of all of the DataWriters that may be sending it DDS data samples. The total number of DataWriters that it can keep track of is set by the initial_remote_writers and max_remote_writers values. For keyed Topics, initial_remote_writers_per_instance and max_remote_writers_per_instance control the number of DataWriters allowed by the DataReader to modify the value of a single instance.

By setting the max value to be less than max_remote_writers, you can prevent instances with many DataWriters from using up the resources and starving other instances. Once the resources for keeping track of DataWriters are used up, the DataReader will not be able to accept “connections” from new DataWriters. The DataReader will not be able to receive data from new matching DataWriters which would be ignored.

In the reliable protocol used by Connext DDS to support a RELIABLE setting for the RELIABILITY QosPolicy, the DataReader must temporarily store DDS data samples that have been received out-of-order from a reliable DataWriter. The storage of out-of-order DDS samples is allocated from the DataReader’s receive queue and shared among all reliable DataWriters. The parameter max_samples_per_remote_writer controls the maximum number of out-of-order data DDS samples that the DataReader is allowed to store for a single DataWriter. This value must be less than the max_samples value set in the RESOURCE_LIMITS QosPolicy.

max_samples_per_remote_writer allows Connext DDS to share the limited resources of the DataReader equitably so that a single DataWriter is unable to use up all of the storage of the DataReader while missing DDS data samples are being resent.

When setting the values of the members, the following rules apply:

If any of the above are false, Connext DDS returns the error code DDS_RETCODE_INCONSISTENT_POLICY when setting the DataReader’s QoS.

max_total_instances and max_instances

The features Durable Reader State, Multi-channel DataWriters, and Persistence Service (Part 6: RTI Persistence Service) require Connext DDS to keep some internal state even for instances without DataWriters or DDS samples in the DataReader’s queue or that have been purged due to a dispose. The additional state is used to filter duplicate DDS samples that could be coming from different DataWriter channels or from multiple executions of Persistence Service. The total maximum number of instances that will be managed by the middleware, including instances without associated DataWriters or DDS samples or that have been purged due to a dispose, is determined by max_total_instances. This additional state will only be kept for up to max_total_instances if keep_minimum_state_for_instances is TRUE, otherwise the additional state will not be kept for any instances.

Example

The max_samples_per_remote_writer value affects sharing and starvation. max_samples_per_remote_writer can be set to less than the RESOURCE_LIMITS QosPolicy’s max_samples to prevent a single DataWriter from starving others. This control is especially important for Topics that have their OWNERSHIP QosPolicy set to SHARED.

In the case of EXCLUSIVE ownership, a lower-strength remote DataWriter can "starve" a higher-strength remote DataWriter by making use of more of the DataReader's resources, an undesirable condition. In the case of SHARED ownership, a remote DataWriter may starve another remote DataWriter, making the sharing not really equal.

Properties

This QosPolicy cannot be modified after the DataReader is created.

It only applies to DataReaders, so there are no restrictions for setting it compatibly on the DataWriter.

Related QosPolicies

Applicable Dds Entities

System Resource Considerations

Increasing any of the “initial” values in this policy will increase the amount of memory allocated by Connext DDS when a new DataReader is created. Increasing any of the “max” values will not affect the initial memory allocated for a new DataReader, but will affect how much additional memory may be allocated as needed over the DataReader’s lifetime.

Setting a max value greater than an initial value thus allows your application to use memory more dynamically and efficiently in the event that the size of the application is not well-known ahead of time. However, Connext DDS may dynamically allocate memory in response to network communications.

© 2016 RTI