RTI Connext Traditional C++ API Version 7.3.0
Public Types | Public Member Functions | Static Public Member Functions | List of all members
rti::flat::Sample< OffsetType > Class Template Reference
RTI Connext DDS API Reference » Topic Module » FlatData Topic-Types » FlatData Samples

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

#include <FlatSample.hpp>

Inherits rti::flat::SampleBase.

Public Types

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

Public Member Functions

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

Static Public Member Functions

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

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 DDSTopic 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 FooDataWriter::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 FooDataWriter::get_loan() or rti::flat::build_data() are DataWriter-managed and do not need to be explicitly deleted. See FooDataWriter::get_loan() for an explanation of the lifecycle of DataWriter-managed samples.

Samples received with a FooDataReader 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

◆ Offset

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

The related Offset type.

This is the template parameter, OffsetType

◆ ConstOffset

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

The related read-only Offset type.

For example, MyFlatMutableOffset::ConstOffset.

Member Function Documentation

◆ root() [1/2]

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
MyFlatFinalOffset
Represents the Offset to an arbitrary user-defined FlatData final IDL struct.
Definition: Offset.hpp:125
MyFlatFinalOffset::my_complex
FlatFinalBar::ConstOffset my_complex() const
Retrieves a const Offset to a complex member.
MyFlatFinalOffset::my_primitive
int32_t my_primitive() const
Retrieves the value for a primitive member.
rti::flat::Sample
The generic definition of FlatData topic-types.
Definition: FlatSample.hpp:148
rti::flat::Sample::root
Offset root()
Provides the Offset to the top-level type.
Definition: FlatSample.hpp:181

◆ root() [2/2]

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
MyFlatMutableOffset::ConstOffset
MyFlatMutableConstOffset ConstOffset
The equivalent read-only Offset type.
Definition: Offset.hpp:213

◆ create_data()

template<typename OffsetType >
Sample< OffsetType > * rti::flat::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 FooDataWriter::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().

◆ clone()

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 FooDataWriter::get_loan or rti::flat::build_data(), the clone this function creates cannot be used in FooDataWriter::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.

◆ delete_data()

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 FooDataWriter::get_loan or rti::flat::build_data().
Postcondition
sample becomes invalid and shouldn't be used