RTI Connext Modern C++ API Version 7.3.0

<<extension>> FlatData Language Binding for IDL topic-types More...

Modules

 FlatData Builders
 A Builder allows creating and initializing variable-size data.
 
 FlatData Samples
 A Sample represents an instance of the IDL topic-type and contains the data in serialized format.
 
 FlatData Offsets
 Offsets provide access to the members of a FlatData Sample.
 

Detailed Description

<<extension>> FlatData Language Binding for IDL topic-types

Note
For a complete description of the FlatData language binding and its benefits, and a tutorial, see the "Sending Large Data" chapter in the RTI Connext User's Manual.
For buildable code examples, see https://community.rti.com/kb/flatdata-and-zerocopy-examples.
The FlatData language binding is available in the Traditional C++ API and in the Modern C++ API.

RTI FlatData™ is a language binding for IDL types in which the in-memory
representation of a sample matches the wire representation. Therefore, the cost of serialization/deserialization is zero.

To select FlatData as the language binding of a type, annotate it with @language_binding(FLAT_DATA) in IDL or apply the attribute languageBinding="flat_data" in XML.

There are some restrictions regarding the kinds of types to which the FlatData language binding can be applied.

Final types are more efficient, but more restrictive. In general, a good compromise is to define mutable top-level types, but making sure their largest data members are final.

When a type is marked with the FlatData language binding, its mapping into C++ is different than that of a regular type (plain language binding). Rather than a single C++ class with direct access to its members, for a FlatData type rtiddsgen generates the following:

For example, for the IDL types MyFlatFinal and MyFlatMutable rtiddsgen generates the following C++ types:

Publishing FlatData

The typical way to publish FlatData samples includes the following steps:

(For final topic-types such as MyFlatFinal)

(For mutable topic-types such as MyFlatMutable)

(For both final and mutable topic-types)

After write, the DataWriter owns the FlatData sample. This allows avoiding additional copies, the main goal of the FlatData language binding. This means that the sample cannot be reused. The DataWriter will return it to the sample pool when appropriate, as described in dds::pub::DataWriter::get_loan.

Subscribing to FlatData

To subscribe to a topic using a FlatData topic-type:

Note that the language binding is a local concept. It is possible to publish with a FlatData topic-type and subscribe to it with a plain topic-type with the same (or assignable) definition. It is also possible to use a plain topic-type on the publisher side and subscribe to it using FlatData. The DataWriter or DataReader of the plain topic-type has to use dds::core::policy::DataRepresentation::xcdr2() in dds::core::policy::DataRepresentation.