3.2.7 Managing Memory for Built-in Types

When a DDS sample is written, the DataWriter serializes it and stores the result in a buffer obtained from a pool of preallocated buffers. In the same way, when a DDS sample is received, the DataReader deserializes it and stores the result in a DDS sample coming from a pool of preallocated DDS samples.

By default, the buffers on the DataWriter and the samples on the DataReader are preallocated with their maximum size. For example:

struct MyString

Unknown macro: { string<128> value; }

This IDL-defined type has a maximum serialized size of 133 bytes (4 bytes for length + 128 characters + 1 NULL terminating character). So the serialization buffers will have a size of 133 bytes. The buffer can hold samples with 128 characters strings. Consequently, the preallocated samples will be sized to keep this length.

However, for built-in types, the maximum size of the buffers/DDS samples is unknown and depends on the nature of the application using the built-in type.

For example, a video surveillance application that is using the keyed octets built-in type to publish a stream of images will require bigger buffers than a market-data application that uses the same built-in type to publish market-data values.

To accommodate both kinds of applications and optimize memory usage, you can configure the maximum size of the built-in types on a per-DataWriter or per-Datareader basis using the 7.5.19 PROPERTY QosPolicy (DDS Extension) . Table 3.1 Properties for Allocating Size of Built-in Types, per DataWriter and DataReader lists the supported built-in type properties. When the properties are defined in the DomainParticipant, they are applicable to all DataWriters and DataReaders belonging to the DomainParticipant, unless they are overwritten in the DataWriters and DataReaders.

These properties must be set consistently with respect to the corresponding *.max_size properties in the DomainParticipant (see Table 3.2 Properties for Allocating Size of Built-in Types, per DomainParticipant). The value of the alloc_size property must be less than or equal to the max_size property with the same name prefix in the DomainParticipant.

Unbounded built-in types are only supported in the C, C++, Java, and .NET APIs.

3.2.7.1 Examples—Setting the Maximum Size for a String Programmatically includes examples of how to set the maximum size of a string built-in type for a DataWriter programmatically, for each API. You can also set the maximum size of the built-in types using XML QoS Profiles. For example, the following XML shows how to set the maximum size of a string built-in type for a DataWriter.

<dds>

<qos_library name="BuiltinExampleLibrary">

        <qos_profile name="BuiltinExampleProfile">

            <datawriter_qos>

                <property>

                    <value>

                        <element>

                        <name>dds.builtin_type.string.alloc_size</name>

                        <value>2048</value>

                        </element>

                    </value>

                </property>

            </datawriter_qos>

            <datareader_qos>

                <property>

                    <value>

                        <element>

                        <name>dds.builtin_type.string.alloc_size</name>

                        <value>2048</value>

                        </element>

                    </value>

                </property>

            </datareader_qos>

        </qos_profile>

    </qos_library>

</dds>

Table 3.1 Properties for Allocating Size of Built-in Types, per DataWriter and DataReader

Built-in Type	Property	Description
string	dds.builtin_type.string.alloc_size	Maximum size of the strings published by the DataWriter or received by the DataReader (includes the NULL-terminated character). Default: dds.builtin_type.string.max_size if defined (see Table 3.2 Properties for Allocating Size of Built-in Types, per DomainParticipant). Otherwise, 1024.
keyedstring	dds.builtin_type.keyed_string. alloc_key_size	Maximum size of the keys used by the DataWriter or DataReader (includes the NULL-terminated character). Default: dds.builtin_type.keyed_string.max_key_size if defined (see Table 3.2 Properties for Allocating Size of Built-in Types, per DomainParticipant). Otherwise, 1024.
	dds.builtin_type.keyed_string. alloc_size	Maximum size of the strings published by the DataWriter or received by the DataReader (includes the NULL-terminated character). Default: dds.builtin_type.keyed_string.max_size if defined (see Table 3.2 Properties for Allocating Size of Built-in Types, per DomainParticipant). Otherwise, 1024.
octets	dds.builtin_type.octets.alloc_size	Maximum size of the octet sequences published by the DataWriter or DataReader. Default: dds.builtin_type.octets.max_size if defined (see Table 3.2 Properties for Allocating Size of Built-in Types, per DomainParticipant). Otherwise, 2048.
keyed-octets	dds.builtin_type.keyed_octets. alloc_key_size	Maximum size of the key published by the DataWriter or received by the DataReader (includes the NULL-terminated character). Default: dds.builtin_type.keyed_octets.max_key_size if defined (see Table 3.2 Properties for Allocating Size of Built-in Types, per DomainParticipant). Otherwise, 1024.
	dds.builtin_type.keyed_octets. alloc_size	Maximum size of the octet sequences published by the DataWriter or DataReader. Default: dds.builtin_type.keyed_octets.max_size if defined (see Table 3.2 Properties for Allocating Size of Built-in Types, per DomainParticipant). Otherwise, 2048.

3.2.7.1 Examples—Setting the Maximum Size for a String Programmatically

For simplicity, error handling is not shown in the following examples.

3.2.7.2 Unbounded Built-in Types

In some scenarios, the maximum size of a built-in type is not known in advance and there is no a reasonable maximum size. For example, this could occur in a file transfer application using the built-in type Octets. Setting a large value for the dds.builtin_type.*.alloc_size property would involve high memory usage.

For the above use case, you can configure the built-in type to be unbounded by setting the property dds.builtin_type.*.alloc_size to the maximum value of a 32-bit signed integer: 2,147,483,647. Then the middleware will not preallocate the DataReader queue's samples to their maximum size. Instead, it will deserialize incoming samples by dynamically allocating and deallocating memory to accommodate the actual size of the sample value.

To configure unbounded support for built-in types:

1. Use these threshold QoS properties:
   • dds.data_writer.history.memory_manager.fast_pool.pool_buffer_max_size on the DataWriter
   • dds.data_reader.history.memory_manager.fast_pool.pool_buffer_max_size on the DataReader (only if keyed)
2. Set the QoS value reader_resource_limits.dynamically_allocate_fragmented_samples on the DataReader to true.
3. For the Java API, also set these properties accordingly for the Java serialization buffer:
   • dds.data_writer.history.memory_manager.java_stream.min_size
   • dds.data_writer.history.memory_manager.java_stream.trim_to_size
   • dds.data_reader.history.memory_manager.java_stream.min_size
   • dds.data_reader.history.memory_manager.java_stream.trim_to_size

See these sections:

• 22.1.3 Writer-Side Memory Management when Using Java
• 22.2.2 Reader-Side Memory Management when Using Java

Unbounded built-in types are only supported in the C, C++, .NET, and Java APIs.

© 2020 RTI