43.3 SYSTEM_RESOURCE_LIMITS QoS Policy (DDS Extension)
The SYSTEM_RESOURCE_LIMITS QosPolicy configures DomainParticipant-independent resources used by Connext. Its main use is to change the maximum number of DomainParticipants that can be created within a single process (address space).
It contains the members shown in Table 43.3 DDS_SystemResourceLimitsQosPolicy. For the valid ranges, please refer to the API Reference HTML documentation.
|
Type |
Field Name |
Description |
|
DDS_Long |
max_objects_per_thread |
Sizes the thread storage that is allocated on a per-thread basis when the thread calls Connext APIs. Leave this property set to the default value to allow the infrastructure to grow as needed. If you wish to strictly control memory allocation, you may set max_objects_per_thread to a smaller value, but note that this runs the risk of a runtime error and reduced application functionality if your limit is reached. See details below. Default: 261120 |
|
DDS_Long |
initial_objects_per_thread |
Sets the initial allocation of the thread storage that is allocated on a per-thread basis when the thread calls Connext APIs. The infrastructure will grow automatically, up to a maximum of max_objects_per_thread, as required by the application at runtime. See details below. Default: 1024 |
max_objects_per_thread controls the size of thread-specific storage that is allocated by Connext for every thread that invokes a Connext API. This storage is used to cache objects that have to be created on a per-thread basis when a thread traverses different portions of Connext internal code.
Instead of dynamically creating and destroying the objects as a thread enters and leaves different parts of the code, Connext caches the objects by storing them in thread-specific storage. We assume that a thread will repeatedly call Connext APIs so that the objects cached will be needed again and again.
The number of objects that will be stored in the cache depends on the number of unique code paths that a thread invokes. It also depends on the number of different DomainParticipants with which the thread interacts.
The number of allowed objects per thread is automatically increased by Connext as needed. (It starts at initial_objects_per_thread and increases as needed, up to max_objects_per_thread.) It is very unlikely that an application will benefit from explicitly setting max_objects_per_thread. See 43.3.4 System Resource Considerations for more discussion.
43.3.1 Properties
This QoS policy cannot be modified after the DomainParticipantFactory is used to create the first DomainParticipant or WaitSet in an application. Therefore, it cannot be set in an XML file—only in code.
This QoS can be set to different values in different applications without affecting interoperability.
43.3.2 Related QoS Policies
There are no interactions with other QosPolicies.
43.3.3 Applicable DDS Entities
43.3.4 System Resource Considerations
max_objects_per_thread is used to determine the size of an array of pointers to objects used in a thread. Increasing max_objects_per_thread will increase the amount of memory allocated by Connext for every thread that accesses Connext code. This includes internal Connext threads as well as user threads.
While a small amount of memory may be conserved by setting max_objects_per_thread carefully, this comes at the risk of generating a runtime exception if an application requires more thread-specific storage than allowed by the max_objects_per_thread value chosen.
If you wish to ensure that the thread-specific storage infrastructure is allocated on application startup rather than on an as-needed basis, set the value of initial_objects_per_thread equal to max_objects_per_thread.
If you are certain that more than the default value of initial_objects_per_thread will be required for your application and you wish to reduce the number of memory allocations performed while your application reaches steady state (i.e., reduce the number of automatic increases), you may set initial_objects_per_thread to a larger number, although usually this is not necessary. To improve the efficiency of memory allocation, Connext may initially size the infrastructure to a larger value than the value of initial_objects_per_thread. The infrastructure will never be sized less than initial_objects_per_thread or greater than max_objects_per_thread.
If you wish to observe when thread-specific storage is dynamically increased, increase the granularity of the debug level to LOCAL and observe the log messages indicating the initial value of max_objects_per_thread and any automatic increases ("Allowed number of thread specific objects is now %d").