DATABASE QosPolicy (DDS Extension)

The Database QosPolicy configures how Connext DDS manages its internal database, including how often it cleans up, the priority of the database thread, and limits on resources that may be allocated by the database. RTI uses an internal in-memory database to store information about entities created locally as well as remote entities found during the discovery process. This database uses a background thread to garbage-collect records related to deleted entities. When the DomainParticipant that maintains this database is deleted, it shuts down this thread..

It includes the members in DDS_DatabaseQosPolicy. For defaults and valid ranges, please refer to the API Reference HTML documentation.

DDS_DatabaseQosPolicy

Type

Field Name

Description

DDS_
ThreadSettings_t

thread.mask

thread.priority

thread.stack_size

Thread settings for the database thread used by Connext DDS to periodically remove deleted records from the database. The values used for these settings are OS-dependent; see the RTI Connext DDS Core Libraries Platform Notes for details.

Note: thread.cpu_list and thread.cpu_rotation are not relevant in this QoS policy.

DDS_Duration_t

shutdown_timeout

The maximum time that the DomainParticipant will wait for the database thread to terminate when the participant is destroyed.

DDS_Duration_t

cleanup_period

The period at which the database thread wakes up to removed deleted records.

DDS_Duration_t

shutdown_cleanup_period

The period at which the database thread wakes up to removed deleted records when the DomainParticipant is being destroyed.

DDS_Long

initial_records

The number of records that is initially created for the database. These records hold information for both local and remote entities that are dynamically created or discovered.

DDS_Long

max_skiplist_level

This is a performance tuning parameter that optimizes the time it takes to search the database for a record. A ‘Skip List’ is an algorithm for maintaining a list that is faster to search than a binary tree.

This value should be set to log2(N), where N is the maximum number of elements that will be stored in a single list. The list that stores the records for remote DataReaders or the one for remote DataWriters tend to have the most entries. So, the number of DataWriters or DataReaders in a system across all DomainParticipants in a single DDS domain, which ever is greater, can be used to set this parameter.

DDS_Long

max_weak_
references

This parameter sets the maximum number of entries in the weak reference table. Weak references are used as a technique for ensuring that unreferenced objects are deleted.

The actual number of weak references is permitted to grow from the value set by initial_weak_references to this maximum.

To prevent Connext DDS from allocating memory for weak references after initialization, you should set the initial and maximum weak references to the same value.

However, it is difficult to calculate how many weak references an application will use. To allowConnext DDS to grow the weak reference table as needed, and thus dynamically allocate memory, you should set the value of this field to DDS_LENGTH_UNLIMITED, the default setting.

DDS_Long

initial_weak_
references

The initial number of entries in the weak reference table.

See max_weak_references.

Connext DDS may decide to use a larger initial value if initial_weak_references is set too small. If you access this parameter after a DomainParticipant has been created, you will see the actual value used.

You may be interested in modifying the shutdown_timeout and shutdown_cleanup_period parameters to decrease the time it takes to delete a DomainParticipant when your application is shutting down.

The DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) controls the memory allocation for elements stored in the database.

Real-time programmers will probably want to adjust the priorities of all of the threads created by Connext DDS relative to each other as well as relative to non-Connext DDS threads in their applications. Connext DDS Threading Model, EVENT QosPolicy (DDS Extension), and RECEIVER_POOL QosPolicy (DDS Extension) discuss the other threads that are created by Connext DDS.

A record in the database can be deleted only when no threads are using it. Connext DDS uses a thread that periodically checks the database if records that have been marked for deletion can be removed. This period is set by cleanup_period. When a DomainParticipant is being destroyed, the thread will wake up faster at the shutdown_cleanup_period as other threads delete and release records in preparation for shutting down.

On Windows and VxWorks systems, the thread that is destroying the DomainParticipant may block up to shutdown_timeout seconds while waiting for the database thread to finish removing all records and terminating. On other operating systems, the thread destroying the DomainParticipant will block as long as required for the database thread to terminate.

The default values for those and the rest of the parameters in this QosPolicy should be sufficient for most applications.

Example

The priority of the database thread should be set to the lowest priority among all threads in a real-time system. Although, the database thread should not be permitted to starve, the work that it performs is non-time-critical.

Properties

This QosPolicy cannot be modified after the DomainParticipant is created.

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

Related QosPolicies

Applicable Dds Entities

System Resource Considerations

Setting the thread parameters correctly on a real-time operating system is usually critical to the proper overall functionality of the applications on that system. Larger values for the thread.stack_size parameter will use up more memory.

Smaller values for the cleanup_period and shutdown_cleanup_period will cause the database thread to wake up more frequently using more CPU.

Connext DDS is permitted to use up more memory for larger values of max_skiplist_level and max_weak_references. Whether or not more memory is actually used depends on actual operating conditions.

© 2018 RTI