The Sequence Data Structure
(This section doesn't apply to the Modern C++ API)
The DDS specification uses sequences whenever a variable-length array of elements must be passed through the API. This includes passing QosPolicies into Connext DDS, as well as retrieving DDS data samples from Connext DDS. A sequence is an ordered collection of elements of the same type. The type of a sequence containing elements of type “Foo” (whether “Foo” is one of your types or a built-in Connext DDS type) is typically called “FooSeq.”
In all APIs except Java, FooSeq contains deep copies of Foo elements; in Java, which does not provide direct support for deep copy semantics, FooSeq contains references to Foo objects. In Java, sequences implement the java.util.List interface, and thus support all of the collection APIs and idioms familiar to Java programmers.
A sequence is logically composed of three things: an array of elements, a maximum number of elements that the array may contain (i.e. its allocated size), and a logical length indicating how many of the allocated elements are valid. The length may vary dynamically between 0 and the maximum (inclusive); it is not permissible to access an element at an index greater than or equal to the length.
A sequence may either “own” the memory associated with it, or it may “borrow” that memory. If a sequence owns its own memory, then the sequence itself will allocate the its memory and is permitted to grow and shrink that memory (i.e. change its maximum) dynamically.
You can also loan a sequence of memory using the sequence-specific operations loan_contiguous() or loan_discontiguous(). This is useful if you want Connext DDS to copy the received DDS data samples directly into data structures allocated in user space.
Please do not confuse (a) the user loaning memory to a sequence with (b) Connext DDS loaning internal memory from the receive queue to the user code via the read() or take() operations. For sequences of user data, these are complementary operations. read() and take() loan memory to the user, passing in a sequence that has been loaned memory with loan_contiguous() or loan_discontinguous().
A sequence with loaned of memory may not change its maximum size.
For C developers:
In C, because there is no concept of a constructor, sequences must be initialized before they are used. You can either set a sequence equal to the macro DDS_SEQUENCE_INITIALIZER or use a sequence-specific method, <type>Seq_initialize(), to initialize sequences.
For C++, C++/CLI, and C# developers:
C++ sequence classes overload the [ ] operators to allow you to access their elements as if the sequence were a simple array. However, for code portability reasons, Connext DDS’s implementation of sequences does not use the Standard Template Library (STL).
For Java developers:
In Java, sequences implement the List interface, and typically, a List must contain Objects; it cannot contain primitive types directly. This restriction makes Lists of primitives types less efficient because each type must be wrapped and unwrapped into and from an Object as it is added to and removed from the List.
Connext DDS provides a more efficient implementation for sequences of primitive types. In Connext DDS, primitive sequence types (e.g., IntSeq, FloatSeq, etc.) are implemented as wrappers around arrays of primitive types. The wrapper also provides the usual List APIs; however, these APIs manipulate Objects that store the primitive type.
More efficient APIs are also provided that manipulate the primitive types directly and thus avoid unnecessary memory allocations and type casts. These additional methods are named according to the pattern <standard method><primitive type>; for example, the IntSeq class defines methods addInt() and getInt() that correspond to the List APIs add() and get(). addInt() and getInt() directly manipulate int values while add() and get() manipulate Objects that contain a single int.
For more information on sequence APIs in all languages, please consult the API Reference HTML documentation (from the main page, select Modules, RTI Connext DDS API Reference, Infrastructure Module, Sequence Support).
© 2018 RTI