For the reliability protocol (and the DURABILITY QosPolicy), this QosPolicy determines the actual maximum queue size when the HISTORY QosPolicy is set to KEEP_ALL.
In general, this QosPolicy is used to limit the amount of system memory that Connext DDS 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 QosPolicy can be set such that an entity does not dynamically allocate any more memory after its initialization phase.
It includes the members in DDS_ResourceLimitsQosPolicy. For defaults and valid ranges, please refer to the API Reference HTML documentation.
|
Type |
Field Name |
Description |
|
DDS_Long |
Maximum number of live DDS samples that Connext DDS can store for a DataWriter/DataReader. This is a physical limit. |
|
|
DDS_Long |
Maximum number of instances that can be managed by a DataWriter/DataReader. For DataReaders, max_instances must be <= max_total_instances in the DATA_READER_RESOURCE_LIMITS QosPolicy (DDS Extension). See also: Example. |
|
|
DDS_Long |
Maximum number of DDS samples of any one instance that Connext DDS will store for a DataWriter/DataReader. For keyed types and DataReaders, this value only applies to DDS samples with an instance state of DDS_ALIVE_INSTANCE_STATE. If a keyed Topic is not used, then max_samples_per_instance must equal max_samples. |
|
|
DDS_Long |
Initial number of DDS samples thatConnext DDS will store for a DataWriter/DataReader. (DDS extension) |
|
|
DDS_Long |
Initial number of instances that can be managed by a DataWriter/DataReader. (DDS extension) |
|
|
DDS_Long |
Number of hash buckets, which are used by Connext DDS to facilitate instance lookup. (DDS extension). |
One of the most important fields is max_samples, which sets the size and causes memory to be allocated for the send or receive queues. For information on how this policy affects reliability, see Tuning Queue Sizes and Other Resource Limits.
When a DataWriter or DataReader is created, the initial_instances and initial_samples parameters determine the amount of memory first allocated for the those Entities. As the application executes, if more space is needed in the send/receive queues to store DDS samples or as more instances are created, then Connext DDS will automatically allocate memory until the limits of max_instances and max_samples are reached.
You may set initial_instances = max_instances and initial_samples = max_samples if you do not want Connext DDS to dynamically allocate memory after initialization.
For keyed Topics, the max_samples_per_instance field in this policy represents maximum number of DDS samples with the same key that are allowed to be stored by a DataWriter or DataReader. This is a logical limit. The hard physical limit is determined by max_samples. However, because the theoretical number of instances may be quite large (as set by max_instances), you may not want Connext DDS to allocate the total memory needed to hold the maximum number of DDS samples per instance for all possible instances (max_samples_per_instance * max_instances) because during normal operations, the application will never have to hold that much data for the Entity.
So it is possible that an Entity will hit the physical limit max_samples before it hits the max_samples_per_instance limit for a particular instance. However, Connext DDS must be able to store max_samples_per_instance for at least one instance. Therefore, max_samples_per_instance must be <= max_samples.
If a keyed data type is not used, there is only a single instance of the Topic, so max_samples_per_instance must equal max_samples.
Once a physical or logical limit is hit, then how Connext DDS deals with new DDS data samples being sent or received for a DataWriter or DataReader is described in the HISTORY QosPolicy setting of DDS_KEEP_ALL_HISTORY_QOS. It is closely tied to whether or not a reliable connection is being maintained.
Although you can set the RESOURCE_LIMITS QosPolicy on Topics, its value can only be used to initialize the RESOURCE_LIMITS QosPolicies of either a DataWriter or DataReader. It does not directly affect the operation of Connext DDS, see Setting Topic QosPolicies.
When using an asynchronous Publisher, if a call to write() is blocked due to a resource limit, the block will last until the timeout period expires, which will prevent others from freeing the resource. To avoid this situation, make sure that the DomainParticipant’s outstanding_asynchronous_sample_allocation in the DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) is always greater than the sum of all asynchronous DataWriters’ max_samples.
When the max_instances limit is reached, a DataWriter will try to make space for a new instance by replacing an existing instance according to the instance replacement kind set in instance_replacement. For the sake of instance replacement, an instance is considered to be unregistered, disposed, or alive. The oldest instance of the specified kind, if such an instance exists, would be replaced with the new instance. Also, all DDS samples of a replaced instance must already have been acknowledged, such that removing the instance would not deprive any existing reader from receiving them.
Since an unregistered instance is one that a DataWriter will not update any further, unregistered instances are replaced before any other instance kinds. This applies for all instance_replacement kinds; for example, the ALIVE_THEN_DISPOSED kind would first replace unregistered, then alive, and then disposed instances. The rest of the kinds specify one or two kinds (e.g DISPOSED and ALIVE_OR_DISPOSED). For the single kind, if no unregistered instances are replaceable, and no instances of the specified kind are replaceable, then the instance replacement will fail. For the others specifying multiple kinds, it either specifies to look for one kind first and then another kind (e.g. ALIVE_THEN_DISPOSED), meaning if the first kind is found then that instance will be replaced, or it will replace either of the kinds specified (e.g. ALIVE_OR_DISPOSED), whichever is older as determined by the time of instance registering, writing, or disposing.
If an acknowledged instance of the specified kind is found, the DataWriter will reclaim its resources for the new instance. It will also invoke the DataWriterListener’s on_instance_replaced() callback (if installed) and notify the user with the handle of the replaced instance, which can then be used to retrieve the instance key from within the callback. If no replaceable instances are found, the new instance will fail to be registered; the DataWriter may block, if the instance registration was done in the context of a write, or it may return with an out-of-resources return code.
In addition, replace_empty_instances (in the DATA_WRITER_RESOURCE_LIMITS QosPolicy (DDS Extension)) configures whether instances with no DDS samples are eligible to be replaced. If this is set, then a DataWriter will first try to replace empty instances, even before replacing unregistered instances.
If you want to be able to store max_samples_per_instance for every instance, then you should set
max_samples >= max_instances * max_samples_per_instance
But if you want to save memory and you do not expect that the running application will ever reach the case where it will see max_instances of instances, then you may use a smaller value for max_samples to save memory.
In any case, there is a lower limit for max_samples:
max_samples >= max_samples_per_instance
If the HISTORY QosPolicy’s kind is set to KEEP_LAST, then you should set:
max_samples_per_instance = HISTORY.depth
This QosPolicy cannot be modified after the Entity is enabled.
There are no requirements that the publishing and subscribing sides use compatible values.
Larger initial_* numbers will increase the initial system memory usage. Larger max_* numbers will increase the worst-case system memory usage.
Increasing instance_hash_buckets speeds up instance-lookup time but also increases memory usage.
© 2018 RTI