44.4 DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension)

The DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy includes various settings that configure how DomainParticipants allocate and use physical memory for internal resources, including the maximum sizes of various properties.

This QosPolicy sets maximum size limits on variable-length parameters used by the participant and its contained Entities. It also controls the initial and maximum sizes of data structures used by the participant to store information about locally-created and remotely-discovered entities (such as DataWriters/DataReaders), as well as parameters used by the internal database to size the hash tables used by the data structures.

By default, a DomainParticipant is allowed to dynamically allocate memory as needed as users create local Entities such as DataWriters and DataReaders or as the participant discovers new applications to store their information. By setting fixed values for the maximum parameters in this QosPolicy, you can bound the memory that can be allocated by a DomainParticipant. In addition, by setting the initial values to the maximum values, you can reduce the amount of memory allocated by DomainParticipants after the initialization period. Notice that memory can still be allocated dynamically after the initialization period. For example, when a new local DataWriter or DataReader is created, the initial memory required for its queue is allocated dynamically.

The maximum sizes of several variable-length parameters—such as the number of partitions that can be stored in the 46.5 PARTITION QosPolicy, the maximum length of data store in the 47.30 USER_DATA QosPolicy and 46.4 GROUP_DATA QosPolicy, and many others—can be changed from their defaults using this QoS. However, it is important that all DomainParticipants that need to communicate with each other use the same set of maximum values. Otherwise, when these parameters are propagated from one DomainParticipant to another, a DomainParticipant with a smaller maximum length may reject the parameter resulting in an error.

This QosPolicy includes the members in Table 44.5 DDS_DomainParticipantResourceLimitsQosPolicy . For defaults and valid ranges, please refer to the API Reference HTML documentation.

DDS_AllocationSettings_t 
{ 
  DDS_Long initial_count;
  DDS_Long max_count;
  DDS_Long incremental_count;
};

Most of the parameters for this QosPolicy are described in the Description column of the table. However, you may need to refer to the sections listed in the column to fully understand the context in which the parameter is used.

An important parameter in this QosPolicy that is often changed by users is the type_object_max_serialized_length. This parameter limits the size of the TypeObject that a DomainParticipant is able to store and propagate for user data types. TypeObjects are the wire representation for a type code. Type codes can be used by external applications to understand user data types without having the data type predefined in compiled form. However, since type codes contain all of the information of a data structure, including the strings that define the names of the members of a structure, complex data structures can result in TypeObjects larger than the default maximum of 8192 bytes. Thus it is common for users to set this parameter to a larger value. However, as with all parameters in this QosPolicy defining maximum sizes for variable-length elements, all DomainParticipants should set the same value for type_object_max_serialized_length.

The <object type> hash_buckets configure the hash-table data structure that is used to efficiently search the database. The optimal number of buckets depend on the actual number of objects that will be stored in the hash table. So if you know how many DataWriters will be created in a DomainParticipant, you may change the value of local_writer_hash_buckets to balance memory usage against search efficiency. A smaller value will use up less memory, but a larger value will make database lookups for the object more efficient.

If you modify any of the <entity type>_data_max_length, max_partitions, or max_partition_cummulative_characters parameters, then you must make sure that they are modified to be the same value for all DomainParticipants in the same DDS domain for all applications. If they are different and an application sends data that is larger than another application is configured to hold, then the two Entities, whether a matching DataWriter/DataReader pair or even two DomainParticipants will fail to connect.

44.4.1 Configuring Resource Limits for Asynchronous DataWriters

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 resource_limits.outstanding_asynchronous_sample_allocation is always greater than the sum of all asynchronous DataWriters’ resource_limits.max_samples (see 47.22 RESOURCE_LIMITS QosPolicy).

44.4.2 Configuring Memory Allocation

The <object type>_allocation configures the number of <object type>’s that can be stored in the internal Connext database. For example, local_writer_allocation configures how many local DataWriters can be created for the DomainParticipant.

The DDS_AllocationSettings_t structure sets the initial and maximum number of each object type that can be stored. The initial_count will determine how many objects are initially allocated, and max_count will determine the maximum amount of objects that Connext is allowed to allocate. The incremental_count is used to allocate more objects in chunks when the number of objects created exceed the initial_count. You can used fixed-size increments or -1 to double the amount of extra memory allocated each time memory is needed.

Notice that the memory pre-allocated for an object using the DDS_AllocationSettings_t structure is not the full memory that will be required by the object during its lifecycle. Memory can still be allocated dynamically when the object is actually used. For example, when a new local DataWriter or DataReader is created, the memory required for its queue is allocated from the heap dynamically at the moment of creation, independently of the DDS_AllocationSettings_t value. The memory pre-allocated for the object by using the DDS_AllocationSettings_t structure only accounts for the memory required to store the object in the internal in-memory database, not its full state.

You should only modify these parameters if you want to decrease the initial memory used by Connext when a DomainParticipant is created or you want to increase the maximum number of local and remote Entities that can be stored in a DomainParticipant.

44.4.3 Example

For most applications, the default values for this QosPolicy may be sufficient. However, if an application uses the PARTITION, USER_DATA, TOPIC_DATA, or GROUP_DATA QosPolicies, the default maximum sizes of the data associated with those policies may need to be adjusted as required by the application. As noted previously, you must make sure that all DomainParticipants in the same DDS domain use the same sets of values or it is possible that Connext will not successfully connect two Entities.

44.4.4 Properties

This QosPolicy cannot be modified after the DomainParticipant is created.

It can be set differently on the publishing and subscribing sides.

44.4.5 Related QosPolicies

• 44.1 DATABASE QosPolicy (DDS Extension)
• 44.3 DISCOVERY_CONFIG QosPolicy (DDS Extension)
• 47.16 MULTI_CHANNEL QosPolicy (DDS Extension)
• 47.30 USER_DATA QosPolicy
• 45.1 TOPIC_DATA QosPolicy
• 46.4 GROUP_DATA QosPolicy
• 46.5 PARTITION QosPolicy
• 47.19 PROPERTY QosPolicy (DDS Extension)

44.4.6 Applicable DDS Entities

• 16.3 DomainParticipants

44.4.7 System Resource Considerations

Memory and CPU usage are directly affected by the values set for parameters of this QosPolicy. See the detailed descriptions above for specifics.