17.1.1 Sequences

A sequence contains an ordered collection of elements that are all of the same type. The operations supported in the sequence are documented in the API Reference HTML documentation, which is available for all supported programming languages (select Modules, RTI Connext API Reference, Infrastructure Module, Sequence Support).

Java sequences implement the java.util.List interface from the standard Collections framework.

In the Modern C++ API, a sequence of type T maps to the type std::vector<T>, or to a type with a similar interface, depending on the options and whether it is bounded or unbounded. See 17.3.4 Translations for IDL Types.

In the C# API, sequences map to a type that implements the System.Collections.Generic.IList<T> interface.

Elements in a sequence are accessed with their index, just like elements in an array. Indices start at zero in all APIs except Ada. In Ada, indices start at 1. Unlike arrays, however, sequences can grow in size. A sequence has two sizes associated with it: a physical size (the "maximum" or "capacity") and a logical size (the "length" or "size"). The physical size indicates how many elements are currently allocated by the sequence to hold; the logical size indicates how many valid elements the sequence actually holds. The length can vary from zero up to the maximum. Elements cannot be accessed at indices beyond the current length.

A sequence may be declared with or without an explicit bound. A sequence's "bound" is the maximum number of elements that the sequence can contain at any one time. A finite bound is very important because it allows Connext to preallocate buffers to hold serialized and deserialized samples of your types; these buffers are used when communicating with other nodes in your distributed system. If a sequence has no bound, Connext will not know how large to allocate its buffers and will therefore have to allocate them on the fly as individual samples are read and written—impacting the latency and determinism of your application.

By default, any sequences found in an IDL file without an explicit bound will be given a default bound of 100 elements. This default value can be overwritten using the RTI Code Generator‘s -sequenceSize command-line argument (see the RTI Code Generator User's Manual).

You can change the default behavior and use unbounded sequences (noting the 17.10 Data Sample Serialization Limits) by using RTI Code Generator's -unboundedSupport command-line argument. When using this option, the generated code will deserialize incoming samples as follows:

  • First, it will release previous memory associated with the unbounded sequences. The memory associated with an unbounded member is not released until the sample containing the member is reused.
  • Second, it will allocate new memory to accommodate the actual size of the unbounded sequences.

To configure unbounded support for code generated with rtiddsgen -unboundedSupport or for DynamicDataWriters/DynamicDataReaders for Topics of types that contain unbounded sequences:

  1. Use these threshold QoS properties:
  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 also: