FlatData Topic-Types

<<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.

• For final types, the FlatData language binding can be applied only to fixed-size types. A fixed-size type is a type whose wire representation always has the same size. This includes primitive types, arrays of fixed-size types, and structs containing only members of fixed-size types. Unions are not fixed-size types.
• For mutable types, any member is permitted.
• Extensible types cannot be marked as FlatData.

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:

• A Sample, the data in serialized format
• An Offset, which allows reading the data members of that type inside a Sample, and modifying them without changing the size
• A Builder, if the type is mutable, which allows creating a variable-size Sample

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

• The Sample types MyFlatFinal and MyFlatMutable
• The Offset types MyFlatFinalOffset and MyFlatMutableOffset.
• The Builder type MyFlatMutableBuilder.

Publishing FlatData

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

• Create a dds::pub::DataWriter as you would for a non-FlatData (plain) topic-type (see Setting up a DataWriter).

(For final topic-types such as MyFlatFinal)

• Obtain a FlatData sample with dds::pub::DataWriter::get_loan.

  MyFlatFinal *foo_sample = writer.get_loan();

• Initialize the sample, starting from the root() offset.

  MyFlatFinalOffset foo_root = foo_sample->root();
  foo_root.my_primitive(3);
  auto my_complex_offset = foo_root.my_complex();
  // ... initialize my_complex_offset 

(For mutable topic-types such as MyFlatMutable)

• Obtain a Builder to create a variable-size sample with rti::flat::build_data().

  MyFlatMutableBuilder foo_builder = rti::flat::build_data(writer);

• Use this builder (and possibly nested member builders) to initialize the members.

  foo_builder.add_my_primitive(3);
  auto my_mutable_builder = foo_builder.build_my_mutable();
  // ... build 'my_mutable' (a member with a mutable type)
  my_mutable_builder.finish(); // completes a member
  auto my_final_offset = foo_builder.add_my_final();
  // ... initialize 'my_final' (a member with a final type)

• Obtain the completed sample with MyFlatMutableBuilder::finish_sample(). After that, the builder is no longer usable, and the sample size cannot change.

  MyFlatMutable *foo_sample = foo_builder.finish_sample();

• Optionally, it is possible to change the values of the sample accessing its root(), as long as the size doesn't change. For example, if the sample was built with a sequence member with two elements, it is possible to modify any of those elements, but it's not possible to add a third element.

(For both final and mutable topic-types)

• Write the sample with dds::pub::DataWriter::write().

  writer.write(*foo_sample);

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:

• Create a dds::sub::DataReader normally (see Setting up a DataReader).
• Read or take the samples using a loaning operation, such as dds::sub::DataReader::take (copying read/take operations cannot be used with FlatData types).
• Access the root() offset, and any of the sample's members from there.

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.