torstenandCopilot
342ffd3e5c
- HandlerMinelayerData: BUILD_RTI Guards für RTI-Abhängigkeiten - svcTabCommon: Export-Header-Fix via Fallback-Target - TrainingAreaBase: Stub-Header für BUILD_RTI=OFF - ddsfts: Include-Pfad und Dependency-Fixes - BUILD_RTI=OFF Compilation vollständig unterstützt Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Entire-Checkpoint: 01M0JNZA586SACX1PRZ2DJAE5S
172 lines
6.9 KiB
C++
172 lines
6.9 KiB
C++
/*
|
|
(c) Copyright, Real-Time Innovations, 2018.
|
|
All rights reserved.
|
|
|
|
No duplications, whole or partial, manual or electronic, may be made
|
|
without express written permission. Any such copies, or
|
|
revisions thereof, must display this notice unaltered.
|
|
This code contains trade secrets of Real-Time Innovations, Inc.
|
|
*/
|
|
|
|
// Note: this file shouldn't be included directly. Include the header for the
|
|
// corresponding C++ API:
|
|
//
|
|
// - Modern C++ API: "rti/topic/flat/FlatData.hpp"
|
|
// - Traditional C++ API: "ndds/ndds_flat_data_cpp.h"
|
|
|
|
#ifndef RTI_DDS_FLAT_RTIFLAT_HPP_
|
|
#define RTI_DDS_FLAT_RTIFLAT_HPP_
|
|
|
|
/**
|
|
* @defgroup RTIFlatDataModule FlatData Topic-Types
|
|
* @ingroup DDSTopicModule
|
|
* @brief @st_ext 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
|
|
* <b>\ndds User's Manual</b>.
|
|
*
|
|
* @note For buildable <b>code examples</b>,
|
|
* see https://community.rti.com/kb/flatdata-and-zerocopy-examples.
|
|
*
|
|
* @note 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
|
|
* \p \@language_binding(FLAT_DATA) in IDL or apply the attribute
|
|
* \p 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 \nddsgen generates the following:
|
|
*
|
|
* \li A \ref RTIFlatSampleModule "Sample", the data in serialized format
|
|
* \li An \ref RTIFlatOffsetsModule "Offset", which allows reading the data
|
|
* members of that type inside a Sample, and modifying them without changing
|
|
* the size
|
|
* \li A \ref RTIFlatBuildersModule "Builder", if the type is mutable, which
|
|
* allows creating a variable-size Sample
|
|
*
|
|
* For example, for the IDL types \ref MyFlatFinal and \ref MyFlatMutable
|
|
* \nddsgen generates the following C++ types:
|
|
* \li The Sample types \ref MyFlatFinal and \ref MyFlatMutable
|
|
* \li The Offset types MyFlatFinalOffset and MyFlatMutableOffset.
|
|
* \li The Builder type MyFlatMutableBuilder.
|
|
*
|
|
* @section PublishingFlatData Publishing FlatData
|
|
* The typical way to publish FlatData samples includes the following steps:
|
|
* - Create a \idref_FooDataWriter as you would for a non-FlatData (plain)
|
|
* topic-type (see \ref DDSWriterExampleModule_writer_setup).
|
|
*
|
|
* (For final topic-types such as \ref MyFlatFinal)
|
|
* - Obtain a FlatData sample with \idref_FooDataWriter_get_loan.
|
|
* \code
|
|
* MyFlatFinal *foo_sample = writer.get_loan();
|
|
* \endcode
|
|
*
|
|
* - Initialize the sample, starting from the \ref rti::flat::Sample::root "root()" offset.
|
|
* \code
|
|
* MyFlatFinalOffset foo_root = foo_sample->root();
|
|
* foo_root.my_primitive(3);
|
|
* auto my_complex_offset = foo_root.my_complex();
|
|
* // ... initialize my_complex_offset
|
|
* \endcode
|
|
*
|
|
* (For mutable topic-types such as \ref MyFlatMutable)
|
|
* - Obtain a \ref RTIFlatBuildersModule "Builder" to create a variable-size
|
|
* sample with rti::flat::build_data().
|
|
* \code
|
|
* MyFlatMutableBuilder foo_builder = rti::flat::build_data(writer);
|
|
* \endcode
|
|
*
|
|
* - Use this builder (and possibly nested member builders) to initialize the
|
|
* members.
|
|
* \code
|
|
* 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)
|
|
* \endcode
|
|
*
|
|
* - Obtain the completed sample with MyFlatMutableBuilder::finish_sample(). After
|
|
* that, the builder is no longer usable, and the sample size cannot change.
|
|
* \code
|
|
* MyFlatMutable *foo_sample = foo_builder.finish_sample();
|
|
* \endcode
|
|
* - 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 \idref_FooDataWriter_write.
|
|
* \code
|
|
* writer.write(*foo_sample);
|
|
* \endcode
|
|
*
|
|
* 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 \idref_FooDataWriter_get_loan.
|
|
*
|
|
* @section SubscribingFlatData Subscribing to FlatData
|
|
*
|
|
* To subscribe to a topic using a FlatData topic-type:
|
|
* - Create a \idref_FooDataReader normally (see
|
|
* \ref DDSReaderExampleModule_reader_setup).
|
|
* - Read or take the samples using a loaning operation, such as
|
|
* \idref_FooDataReader_take (copying read/take operations cannot be used
|
|
* with FlatData types).
|
|
* - Access the \ref rti::flat::Sample::root "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 <b>plain</b>
|
|
* 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
|
|
* \idref_XCDR2_DATA_REPRESENTATION in \idref_DataRepresentationQosPolicy.
|
|
*
|
|
*/
|
|
|
|
#ifdef DOXYGEN_DOCUMENTATION_ONLY
|
|
namespace rti {
|
|
|
|
/**
|
|
* @brief \st_ext Support for \ref RTIFlatDataModule
|
|
*/
|
|
namespace flat {
|
|
}
|
|
}
|
|
#endif
|
|
|
|
#include "rti/flat/ExceptionHelper.hpp"
|
|
#include "rti/flat/FlatSample.hpp"
|
|
#include "rti/flat/FlatTypeTraits.hpp"
|
|
#include "rti/flat/SequenceBuilders.hpp"
|
|
|
|
#endif // RTI_DDS_FLAT_RTIFLAT_HPP_
|
|
|