47.6 DATA_WRITER_RESOURCE_LIMITS QosPolicy (DDS Extension)
This QosPolicy defines various settings that configure how DataWriters allocate and use physical memory for internal resources.
It includes the members in Table 47.15 DDS_DataWriterResourceLimitsQosPolicy. For defaults and valid ranges, please refer to the API Reference HTML documentation.
|
Type |
Field Name |
Description |
|
DDS_Long |
Initial number of threads that are allowed to concurrently block on the write()call on the same DataWriter. |
|
|
DDS_Long |
Maximum number of threads that are allowed to concurrently block on write() call on the same DataWriter. |
|
|
DDS_Long |
Maximum number of remote DataReaders for which this DataWriter will perform content-based filtering. |
|
|
DDS_Long |
Initial number of batches that a DataWriter will manage if batching is enabled. |
|
|
DDS_Long |
Maximum number of batches that a DataWriter will manage if batching is enabled. When batching is enabled, the maximum number of DDS samples that a DataWriter can store is limited by this value and max_samples in 47.22 RESOURCE_LIMITS QosPolicy. |
|
|
DDS_DataWriter |
Sets the kinds of instances allowed to be replaced when a DataWriter reaches max_instances in the 47.22 RESOURCE_LIMITS QosPolicy. (See 47.6.1 Configuring DataWriter Instance Replacement.) |
|
|
DDS_Boolean |
Whether to replace empty instances during instance replacement. (See 47.6.1 Configuring DataWriter Instance Replacement.) |
|
|
DDS_Boolean |
Whether to automatically register instances written with non-NIL handle that are not yet registered, which will otherwise return an error. This can be especially useful if the instance has been replaced. |
|
|
DDS_Long |
Initial number of virtual writers supported by a DataWriter. |
|
|
DDS_Long |
Maximum number of virtual writers supported by a DataWriter. Sets the maximum number of unique virtual writers supported by a DataWriter, where virtual writers are added when DDS samples are written with the virtual writer GUID. This field is especially relevant in the configuration of Persistence Service DataWriters, since they publish information on behalf of multiple virtual writers. |
|
|
DDS_Long |
max_remote_readers |
The maximum number of remote readers supported by a DataWriter. |
|
DDS_Long |
max_app_ack_remote_readers |
The maximum number of application-level acknowledging remote readers supported by a DataWriter. |
|
DDS_Long |
initial_active_topic_queries |
Initial number of active topic queries a DataWriter will manage. |
|
DDS_Long |
max_active_topic_queries |
Maximum number of active topic queries a DataWriter will manage. When topic queries are enabled, the maximum number of topic queries that a DataWriter can process at the same time is limited by this value. |
|
DDS_AllocationSettings_t |
writer_loaned_sample_allocation |
Sets the allocation settings of the DataWriter-managed sample pool, when using Zero Copy transfer over shared memory or FlatData language binding. The number of samples loaned by a DataWriter via FooDataWriter’s get_loan() operation is limited by the max_count in writer_loaned_sample_allocation. See 34. Sending Large Data. |
|
DDS_Boolean |
initialize_writer_loaned_sample |
Determines whether or not to initialize members to default values in loaned samples returned by FooDataWriter's get_loan() operation, when using Zero Copy transfer over shared memory or FlatData language binding. See 34. Sending Large Data. |
DataWriters must allocate internal structures to handle the simultaneous blocking of threads trying to call write() on the same DataWriter, for the storage used to batch small DDS samples, and for content-based filters specified by DataReaders.
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 a DataWriter can use. By setting the initial size to the maximum size, you will prevent Connext from dynamically allocating any memory after the creation of the DataWriter.
When setting the fields in this policy, the following rule applies. If this is false, Connext returns DDS_RETCODE_INCONSISTENT_POLICY:
- max_concurrent_blocking_threads >= initial_concurrent_blocking_threads
The initial_concurrent_blocking_threads is used to allocate necessary initial system resources. If necessary, it will be increased automatically up to the max_concurrent_blocking_threads limit.
Every user thread calling write() on a DataWriter may use a semaphore that will block the thread when the DataWriter’s send queue is full. Because user code may set a timeout, each thread must use a different semaphore. See the max_blocking_time parameter of the 47.21 RELIABILITY QosPolicy. This QoS is offered so that the user application can control the dynamic allocation of system resources by Connext.
If you do not mind if Connext dynamically allocates semaphores when needed, then you can set the max_concurrent_blocking_threads parameter to some large value like MAX_INT. However, if you know exactly how many threads will be calling write() on the same DataWriter, and you do not want Connext to allocate any system resources or memory after initialization, then you should set:
max_concurrent_blocking_threads = initial_concurrent_blocking_threads = NUM
(where NUM is the number of threads that could possibly block concurrently).
Each DataWriter can perform content-based data filtering for up to max_remote_reader_filters number of DataReaders.
Values for max_remote_reader_filters may be.
- 0: The DataWriter will not perform filtering for any DataReader, which means the DataReader will have to filter the data itself.
- 1 to (231-2): The DataWriter will filter for up to the specified number of DataReaders. In addition, the Datawriter will store the result of the filtering per DDS sample per DataReader.
- DDS_LENGTH_UNLIMITED (default): The DataWriter will filter for up to (231)-2 DataReaders. However, in this case, the DataWriter will not store the filtering result per DDS sample per DataReader. Thus, if a DDS sample is resent (such as due to a loss of reliable communication), the DDS sample will be filtered again.
For more information, see 18.3 ContentFilteredTopics.
47.6.1 Configuring DataWriter Instance Replacement
When the max_instances limit (in the 1.1 DATA_WRITER_RESOURCE_LIMITS QosPolicy (DDS Extension)) 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 in the 47.6 DATA_WRITER_RESOURCE_LIMITS QosPolicy (DDS Extension). 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 47.6 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.
47.6.2 Example
If there are multiple threads that can write on the same DataWriter, and the write() operation may block (based on reliability_qos.max_blocking_time and HISTORY settings), you may want to set initial_concurrent_blocking_threads to the most likely number of threads that will block on the same DataWriter at the same time, and set max_concurrent_blocking_threads to the maximum number of threads that could potentially block in the worst case.
47.6.3 Properties
This QosPolicy cannot be modified after the DataWriter is created.
Since it is only for DataWriters, there are no compatibility restrictions for how it is set on the publishing and subscribing sides.
47.6.4 Related QosPolicies
47.6.5 Applicable DDS Entities
47.6.6 System Resource Considerations
Increasing the values in this QosPolicy will cause more memory usage and more system resource usage.