FlatData Builders

A Builder allows creating and initializing variable-size data. More...

Classes
class	rti::flat::AggregationBuilder
	Base class of struct and union builders. More...
class	rti::flat::UnionBuilder< Discriminator >
	Base class of builders for user-defined mutable unions. More...
class	MyFlatMutableBuilder
	Represents the Builder for an arbitrary user-defined mutable type. More...
class	MyFlatUnionBuilder
	Represents the Builder for an arbitrary user-defined mutable IDL union. More...
class	rti::flat::AbstractBuilder
	Base class of all Builders. More...
class	rti::flat::AbstractListBuilder
	Base class of all array and sequence builders. More...
class	rti::flat::MutableArrayBuilder< ElementBuilder, N >
	Builds an array member of variable-size elements. More...
class	rti::flat::AbstractSequenceBuilder
	Base class of Builders for sequence members. More...
class	rti::flat::MutableSequenceBuilder< ElementBuilder >
	Builds a sequence member of variable-size elements. More...
class	rti::flat::FinalSequenceBuilder< ElementOffset >
	Builds a sequence member of fixed-size elements. More...
class	rti::flat::PrimitiveSequenceBuilder< T >
	Builds a sequence of primitive members. More...
class	rti::flat::StringBuilder
	Builds a string. More...

Functions
template<typename TopicType >
rti::flat::flat_type_traits< TopicType >::builder	rti::flat::build_data (dds::pub::DataWriter< TopicType > &writer)
	Begins building a new sample. More...
template<typename TopicType >
void	rti::flat::discard_builder (dds::pub::DataWriter< TopicType > &writer, typename rti::flat::flat_type_traits< TopicType >::builder &builder)
	Discards a sample builder. More...

Detailed Description

A Builder allows creating and initializing variable-size data.

Builders allow creating variable-size FlatData samples, as described in Publishing FlatData.

There are the following Builder types:

Category	Builder type
User types	For example: MyFlatMutableBuilder, a mutable struct MyFlatUnionBuilder, a union Final structs are fixed-size and do not have a Builder (see for example MyFlatMutableBuilder::add_my_final()).
Arrays	rti::flat::MutableArrayBuilder Arrays of final elements are fixed-size and do not have a Builder (see for example MyFlatMutableBuilder::add_my_final_array()).
Sequences	rti::flat::MutableSequenceBuilder for sequences of mutable elements rti::flat::FinalSequenceBuilder for sequences of final elements rti::flat::PrimitiveSequenceBuilder for sequences of primitive elements rti::flat::StringBuilder
Primitive types	Primitive members are added using one of the member functions of the Builder of the type that contains them. See for example MyFlatMutableBuilder::add_my_primitive()<

Builder for user types, such as MyFlatMutableBuilder, can behave as sample builders, when they build a sample, or member builders when they build a member for another Builder (such as the Builder returned by MyFlatMutableBuilder::build_my_mutable()). All the other Builder types (sequences, arrays) are always member builders (such as the Builder returned by MyFlatMutableBuilder::build_my_final_seq()).

Builders are move-only types. They cannot be copied, only moved. When you assign a Builder as the return value of a function, this happens automatically.

// the return value of 'build_data' is moved into 'builder'
MyFlatMutableBuilder builder = rti::flat::build_data(writer);

To explicitly move a Builder variable use std::move() in C++11 platforms or call the move() member function in pre-C++11 platforms.

Builder Error Management

In the Modern C++ API errors are notified with exceptions. Builder operations may throw the following exceptions

• dds::core::PreconditionNotMetError, for any precondition failure.
• dds::core::OutOfResourcesError, when the Builder's underlying buffer runs out of space (this should not happen when the Builder has been created with rti::flat::build_data()).

See also Offset Error Management.

See also

MyFlatMutableBuilder for more information specific to builders for user types.

Function Documentation

build_data()

template<typename TopicType >

rti::flat::flat_type_traits< TopicType >::builder rti::flat::build_data

(

dds::pub::DataWriter< TopicType > &

writer

)

Begins building a new sample.

Template Parameters

TopicType

A FlatData mutable type that corresponds to the type of the DataWriter argument.

Parameters

writer

The writer that will be used to write this sample.

Returns

The Builder to build the sample. For example if TopicType is MyFlatMutable, this function returns a MyFlatMutableBuilder.

Once you have completed the sample, call finish_sample() to obtain a MyFlatMutable sample that can be written with writer.

If the building of this sample needs to be aborted before calling finish_sample(), use rti::flat::discard_builder(). If, after obtaining a sample with finish_sample(), this sample is not written, then discard it with dds::pub::DataWriter::discard_loan().

See also

dds::pub::DataWriter::get_loan, the function that build_data() uses to obtain the memory required to build the sample.

Publishing FlatData

References dds::pub::DataWriter< T >::get_loan().

discard_builder()

template<typename TopicType >

void rti::flat::discard_builder	(	dds::pub::DataWriter< TopicType > &	writer,
		typename rti::flat::flat_type_traits< TopicType >::builder &	builder
	)

Discards a sample builder.

Template Parameters

TopicType

An IDL-defined FlatData type that corresponds to the type of the DataWriter argument.

This function invalidates and discards a builder before it is finished() and before the sample it would have created was written.

Parameters

writer	The writer that was used to create the builder
builder	The builder, created with rti::flat::build_data(writer);

References dds::pub::DataWriter< T >::discard_loan().