|
RTI Connext Micro C API
Version 2.4.14.1
|
|
RTI Connext Micro C API
Version 2.4.14.1
|
<<cert>> Specifies the resources that RTI Connext Micro can consume in order to meet the requested QoS. More...
Data Fields | |
| DDS_Long | max_samples |
| Represents the maximum samples the middleware can store for any one DDS_DataWriter or DDS_DataReader. | |
| DDS_Long | max_instances |
| Represents the maximum number of instances a DDS_DataWriter (or DDS_DataReader) can manage. | |
| DDS_Long | max_samples_per_instance |
| Represents the maximum number of samples of any one instance a DDS_DataWriter or DDS_DataReader can manage. | |
<<cert>> Specifies the resources that RTI Connext Micro can consume in order to meet the requested QoS.
This policy controls the resources that RTI Connext Micro can use in order to meet the requirements imposed by the application and other QoS settings.
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 RELIABILITY. If reliability is DDS_BEST_EFFORT_RELIABILITY_QOS then RTI Connext Micro is allowed to drop samples. If the reliability is DDS_RELIABLE_RELIABILITY_QOS, RTI Connext Micro will block the DDS_DataWriter or discard the sample at the DDS_DataReader in order not to lose existing samples.
All limits must be set to positive finite values. Furthermore, max_samples must be large enough to contain all samples for all instances:
The setting of RESOURCE_LIMITS max_samples_per_instance must be consistent with the HISTORY depth. For these two QoS to be consistent, they must verify that depth <= max_samples_per_instance.
| DDS_Long DDS_ResourceLimitsQosPolicy::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.
The DDS_ResourceLimitsQosPolicy::max_samples resource-limit limits the maximum number of samples a DDS_DataReader can allocate and cache. Samples are cached before they are made available to the application; for example, when samples are received out-of-order. Thus, this resource limit may impact throughput and latency.
What this value should be set to is determined by a number of factors:
The DDS_ResourceLimitsQosPolicy::max_samples resource-limit limits the maximum number of samples a DDS_DataWriter can allocate and maintain state for at any given time. Every time a write operation is called, a sample is allocated from the cache and filled in with user-data.
A sample allocated from the pool controlled by this resource-limit can be reused based on the following rules:
For best-effort communication, this resource-limit can be set to 1.
For reliable communication, the value of this resource-limit determines the maximum number of samples a DDS_DataWriter can keep in unacknowledged state before reusing potentially unacknowledged samples (for DDS_KEEP_LAST_HISTORY_QOS). For reliable data, the value should take into account the data-rate, the DDS_RtpsReliableWriterProtocol_t::heartbeat_period, and DDS_RtpsReliableWriterProtocol_t::heartbeats_per_max_samples.
[default] 1
[range] [1, 100 million] >= (max_samples_per_instance * max_instances),
| DDS_Long DDS_ResourceLimitsQosPolicy::max_instances |
Represents the maximum number of instances a DDS_DataWriter (or DDS_DataReader) can manage.
The max_instance resource-limit limits the maximum number of instances a DDS_DataReader can manage. Instance state is one of the most expensive resources to maintain, as well as often being the highest one.
The resources allocated by an instance are normally only released when an instance is disposed and all known owners have unregistered the instance; please refer to FooDataWriter_unregister_instance and FooDataWriter_dispose.
The DDS_DataReaderResourceLimitsQosPolicy::instance_replacement policy is useful to maintain state for only the last N instances, and when it is not necessary to keep samples in the DDS_DataReader history cache. When the DDS_DataReaderResourceLimitsQosPolicy::instance_replacement policy is set to replace the oldest instance (DDS_REPLACE_OLDEST_INSTANCE_REPLACEMENT_QOS), information about the oldest instance is automatically removed and the newly discovered instance is received. The disadvantage is that DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE state cannot be maintained. The DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE is maintained for an instance that is accepted (either there is space or another instance is replaced), regardless of whether any samples have previously been received.
The DDS_ResourceLimitsQosPolicy::max_instances resource limit limits the maximum number of instances a DDS_DataWriter can manage. An instance resource can only be reused when it is unregistered by the DDS_DataWriter.
[default] 1
[range] [1, 1 million]
| DDS_Long DDS_ResourceLimitsQosPolicy::max_samples_per_instance |
Represents the maximum number of samples of any one instance a DDS_DataWriter or DDS_DataReader can manage.
This resource-limit limits the maximum number of samples that can be cached for a single instance; it must be less than or equal to max_samples and greater or equal to the history depth. When DDS_ResourceLimitsQosPolicy::max_samples_per_instance is higher than depth, it makes it possible to loan samples and receive up to depth samples before returning loaned samples.
When this resource-limit or DDS_HistoryQosPolicy::depth is exceeded and the DDS_HistoryQosPolicy::kind is DDS_KEEP_LAST_HISTORY_QOS, the oldest sample is removed from the cache.
Note that it is possible to exceed the max_samples_per_instance limit while samples are being received and processed, but before they are added to the reader queue. This typically happens when there are holes in the sequence numbers that must be filled before the samples can be committed to the reader queue. If a sample cannot be committed due to the max_samples_per_instance limit, it is not dropped. Instead, it is recommitted when space is made available, such as the application taking samples from the reader queue or older samples being removed due to KEEP_LAST.
For unkeyed types this value has to be equal to max_samples.
This resource-limit limits the maximum number of samples that can be cached for a single instance; it must be less than or equal to max_samples and greater or equal to the DDS_HistoryQosPolicy::depth.
DDS_HistoryQosPolicy::depth determines how many samples are kept in case of DDS_TRANSIENT_LOCAL_DURABILITY_QOS durability and made available to late joining DDS_DataReader, while DDS_ResourceLimitsQosPolicy::max_samples_per_instance is the maximum number of unacknowledged samples the DDS_DataWriter can keep per instance. Thus, if max_samples_per_instance > depth, it is possible to keep unacknowledged samples while limiting the number of samples made available to late joining DataReaders.
[default] 1
[range] [1, 100 million], <= max_samples, >= DDS_HistoryQosPolicy::depth
RTI Connext Micro C API Version 2.4.14.1
Copyright © Thu Nov 2 2023
Real-Time Innovations, Inc
