RTI Connext Modern C++ API  Version 6.0.1
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
rti::flat::Sample< OffsetType > Class Template Reference

The generic definition of FlatData topic-types. More...

#include <FlatSample.hpp>

Inherits rti::flat::SampleBase.

Public Types

typedef OffsetType Offset
 The related Offset type.
 
typedef OffsetType::ConstOffset ConstOffset
 The related read-only Offset type.
 

Public Member Functions

Offset root ()
 Provides the Offset to the top-level type.
 
ConstOffset root () const
 Provides the Offset to the top-level type.
 
Sample< OffsetType > * clone () const
 Clones a Sample, creating an unmanaged Sample.
 

Static Public Member Functions

static Sample< OffsetType > * create_data ()
 Creates an unmanaged FlatData Sample.
 
static void delete_data (rti::flat::Sample< OffsetType > *sample)
 Releases an unmanaged Sample.
 

Detailed Description

template<typename OffsetType>
class rti::flat::Sample< OffsetType >

The generic definition of FlatData topic-types.

Template Parameters
OffsetTypeThe Offset to the beginning of the data Sample (the root), for example MyFlatFinalOffset, or MyFlatMutableOffset.

For a FlatData IDL type, rtiddsgen generates an instantiation of this class, such as MyFlatFinal or MyFlatMutable. That's the topic-type used to declare a dds::topic::Topic and write or read FlatData samples.

A FlatData Sample owns an inline buffer that contains the serialized data. To access the Sample data members we use Offsets, iterators that point to the position of a member in the Sample buffer. The root() is the Offset to the top-level element (for example MyFlatMutableOffset). From there MyFlatMutableOffset's member functions provide access to its members.

The method to create a Sample varies depending on whether the type is final or mutable.

Samples of final FlatData types always have the same size, and can be obtained directly with dds::pub::DataWriter::get_loan().

Samples of mutable FlatData types need to be "built" using the Builder returned by rti::flat::build_data() (MyFlatMutableBuilder in this example). A Builder allows adding each member individually in any order, and sizing sequences as needed.

See Publishing FlatData for code snippets.

Samples created with dds::pub::DataWriter::get_loan() or rti::flat::build_data() are DataWriter-managed and do not need to be explicitly deleted. See dds::pub::DataWriter::get_loan() for an explanation of the lifecycle of DataWriter-managed samples.

Samples received with a dds::sub::DataReader can be examined by obtaining the root(), but cannot be modified. See Subscribing to FlatData.

FlatData samples are not value types. They don't provide copy constructors or assignment operators, because of their definition as an inline buffer that contains the serialized Sample at all times. A Sample can be cloned with the static function clone(). A cloned Sample is unmanaged and has to be deleted with the static function delete_data().

Member Typedef Documentation

template<typename OffsetType >
typedef OffsetType rti::flat::Sample< OffsetType >::Offset

The related Offset type.

This is the template parameter, OffsetType

template<typename OffsetType >
typedef OffsetType::ConstOffset rti::flat::Sample< OffsetType >::ConstOffset

The related read-only Offset type.

For example, MyFlatMutableOffset::ConstOffset.

Member Function Documentation

template<typename OffsetType >
Offset rti::flat::Sample< OffsetType >::root ( )
inline

Provides the Offset to the top-level type.

Returns
An Offset that allows reading and modifying the members of this Sample, for example MyFlatFinalOffset or MyFlatMutableOffset.

This overload allows modifying the Sample.

Example:

MyFlatFinal *my_sample = ...; // for example, created with DataWriter::get_loan()
MyFlatFinalOffset my_sample_root = my_sample->root();
my_sample_root.my_primitive(33);
auto my_member_offset = my_sample_root.my_complex();
// ... modify my_member_offset
template<typename OffsetType >
ConstOffset rti::flat::Sample< OffsetType >::root ( ) const
inline

Provides the Offset to the top-level type.

Returns
An Offset that allows reading the members of this Sample. For example, MyFlatFinalOffset::ConstOffset or MyFlatMutableOffset::ConstOffset.

This overload doesn't allow modifying the Sample.

Example:

const MyFlatMutable *my_sample = ...; // for example, read from a DataReader
MyFlatMutableOffset::ConstOffset my_sample_root = my_sample->root();
std::cout << my_sample_root.my_primitive() << std::endl;
auto my_member_offset = my_sample_root.my_mutable_seq();
// ... read my_member_offset
template<typename OffsetType >
Sample< OffsetType > * Sample< OffsetType >::create_data ( )
static

Creates an unmanaged FlatData Sample.

Note
In general on the publication side it is recommended to create DataWriter-managed samples using dds::pub::DataWriter::get_loan (for final types) and rti::flat::build_data() (for mutable types).

If the topic-type is final, the returned Sample can be initialized by obtaining the root().

If the topic-type is mutable, the resulting Sample has no members, and root() returns a null Offset. The result of create_data() must be used to create a Builder. This is a rare use case, and rti::flat::build_data() should be used in most situations.

In all cases, the returned Sample must be explicitly deleted with delete_data().

template<typename OffsetType >
Sample<OffsetType>* rti::flat::Sample< OffsetType >::clone ( ) const
inline

Clones a Sample, creating an unmanaged Sample.

Warning
When this Sample has been created with dds::pub::DataWriter::get_loan or rti::flat::build_data(), the clone this function creates cannot be used in dds::pub::DataWriter::write(), because the DataWriter is managing the lifecycle of its samples.

Creates a new Sample and copies the underlying serialized buffer.

delete_data() must be called to release the Sample.

template<typename OffsetType >
static void rti::flat::Sample< OffsetType >::delete_data ( rti::flat::Sample< OffsetType > *  sample)
inlinestatic

Releases an unmanaged Sample.

Unmanaged samples are those created with create_data() or clone().

Precondition
sample cannot have been created with dds::pub::DataWriter::get_loan or rti::flat::build_data().
Postcondition
sample becomes invalid and shouldn't be used

RTI Connext Modern C++ API Version 6.0.1 Copyright © Sat Nov 23 2019 Real-Time Innovations, Inc