Builder.hpp

/*
(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.
*/

#ifndef RTI_DDS_FLAT_BUILDER_HPP_
#define RTI_DDS_FLAT_BUILDER_HPP_

#include "xcdr/xcdr_stream.h"
#include "xcdr/xcdr_stream_impl.h"
#include "xcdr/xcdr_interpreter.h"
#include "xcdr/xcdr_interpreter.h"

#include "rti/xcdr/Stream.hpp"
#include "rti/flat/ExceptionHelper.hpp"
#include "rti/flat/SequenceOffsets.hpp"

#ifdef DOXYGEN_DOCUMENTATION_ONLY

class NDDSUSERDllExport MyFlatMutableBuilder : public rti::flat::AggregationBuilder {
  public:
    typedef MyFlatMutableOffset Offset;

    MyFlatMutableBuilder()
    {
    }

    MyFlatMutableBuilder(
            unsigned char *buffer, 
            int32_t size,
            bool initialize_members = false)
    {
    }

    Offset finish();

    MyFlatMutable * finish_sample();

    bool add_my_primitive(int32_t value);

    bool add_my_optional_primitive(int32_t value);

    rti::flat::PrimitiveArrayOffset<int32_t, 10> add_my_primitive_array();

    rti::flat::PrimitiveSequenceBuilder<int32_t> build_my_primitive_seq();

    MyFlatFinalOffset add_my_final();

    rti::flat::FinalAlignedArrayOffset<MyFlatFinalOffset, 10> add_my_final_array();

    rti::flat::FinalSequenceBuilder<MyFlatFinalOffset> build_my_final_seq();

    FlatMutableBarBuilder build_my_mutable();

    rti::flat::MutableArrayBuilder<FlatMutableBarBuilder, 10> build_my_mutable_array();

    rti::flat::MutableSequenceBuilder<FlatMutableBarBuilder > build_my_mutable_seq();

    rti::flat::StringBuilder build_my_string();

    rti::flat::MutableSequenceBuilder<rti::flat::StringBuilder > build_my_string_seq();
};

class MyFlatUnionBuilder : public rti::flat::UnionBuilder<int32_t> {
public:
    typedef MyFlatUnionOffset Offset;
    

    MyFlatUnionBuilder()
    {
    }

    Offset finish();


    MyFlatUnion * finish_sample();

    bool add_my_primitive(int32_t value);

    MyFlatMutableBuilder build_my_mutable(int32_t discriminator = 1);

    MyFlatFinal::Offset add_my_final();
};

#endif

namespace rti { namespace flat {

// Support for move constructor and assignment operator in C++98
//
// All concrete subclasses of AbstractBuilder must use this macro to implement
// move semantics
//
#if defined(RTI_FLAT_DATA_CXX11_RVALUE_REFERENCES)
#define RTI_FLAT_BUILDER_DEFINE_MOVE_OPERATIONS_IMPL(TYPE, BASE, PROXY)
#define RTI_FLAT_BUILDER_DEFINE_MOVE_OPERATIONS(TYPE, BASE)
#define RTI_FLAT_MOVE_BUILDER(BUILDER) BUILDER
#else
#define RTI_FLAT_BUILDER_DEFINE_MOVE_OPERATIONS_IMPL(TYPE, BASE, PROXY) \
public: \
    TYPE(PROXY other) throw() \
    { \
        move_from(other); \
    } \
    TYPE& operator=(PROXY other) throw() \
    { \
        finish_untyped_impl(); \
        move_from(other); \
        return *this; \
    } \
    TYPE move() \
    { \
        return TYPE(PROXY(*this)); \
    } \
private: \
    TYPE(TYPE&); \
    TYPE& operator=(TYPE&);

// Shortcut for generated IDL types
#define RTI_FLAT_BUILDER_DEFINE_MOVE_OPERATIONS(TYPE, BASE) \
    RTI_FLAT_BUILDER_DEFINE_MOVE_OPERATIONS_IMPL( \
        TYPE, BASE, UntypedAggregationBuilderMoveProxy)

#define RTI_FLAT_MOVE_BUILDER(BUILDER) (BUILDER).move()
#endif

namespace detail {
    // Template parameters can be AbstractBuilder or AbstractBuilderMoveProxy
    template <typename Builder1, typename Builder2>
    void move_abstract_builder(Builder1& to, Builder2& from)
    {
        if (from.parent_builder_ == NULL) {
            to.owned_stream_ = from.owned_stream_;
        }

        to.parent_stream_ = from.parent_stream_;
        to.parent_builder_ = from.parent_builder_;
        to.begin_position_ = from.begin_position_;
        to.bind_position_ = from.bind_position_;
        to.initialize_on_add_ = from.initialize_on_add_;
#ifdef RTI_FLAT_DATA_NO_EXCEPTIONS
        to.failure_ = from.failure_;
#endif

        from.parent_stream_ = NULL;
        from.parent_builder_ = NULL;
        from.bind_position_ = NULL;
        from.begin_position_ = NULL;
    }
}

/*
 * @brief Provides the functionality common to all builders
 * 
 * This class is the base of all builders and provides the following 
 * functionality:
 * 
 * - Get the buffer and its size
 * - Add final elements (base case)
 * - Build operations--create nested builders, binding (base case)
 * - Finish operation--unbind (base case)
 * - Discard operation--throw away a nested Builder and roll back the parent
 * - Error management when exceptions are not supported (traditional C++)
 * - Move semantics (base case)
 */
class AbstractBuilder {
protected:
    AbstractBuilder()
        : parent_stream_(NULL),
          parent_builder_(NULL),
          begin_position_(NULL),
          bind_position_(NULL),
          initialize_on_add_(false)
#ifdef RTI_FLAT_DATA_NO_EXCEPTIONS
          , failure_(false)
#endif          
    {
    }

    /*i
     * @brief Create a new top-level Builder
     */
    AbstractBuilder(unsigned char *buffer, offset_t size, bool initialize_members)
        : parent_stream_(NULL),
          parent_builder_(NULL),
          bind_position_(NULL),
          initialize_on_add_(initialize_members)
#ifdef RTI_FLAT_DATA_NO_EXCEPTIONS
          , failure_(false)
#endif
    {
        // Serializes the encapsulation into the buffer and initializes the
        // stream with that buffer and that encapsulation
        if (!RTIXCdrFlatSample_initializeEncapsulationAndStream(
                (char *) buffer, 
                &owned_stream_.c_stream(),
                RTIXCdrEncapsulationId_getNativePlCdr2(), 
                size)) {
            RTI_FLAT_BUILDER_OUT_OF_RESOURCES_ERROR(return);
        }

        begin_position_ = owned_stream_.current_position();
    }

protected:
    template <typename Builder1, typename Builder2>
    friend void detail::move_abstract_builder(Builder1& to, Builder2& from);

#if defined(RTI_FLAT_DATA_CXX11_RVALUE_REFERENCES)
    AbstractBuilder(AbstractBuilder&& other)
    {
        detail::move_abstract_builder(*this, other);
    }

    AbstractBuilder& operator=(AbstractBuilder&& other)
    {
        if (this == &other) {
            return *this;
        }

        finish_untyped_impl();

        detail::move_abstract_builder(*this, other);

        return *this;
    }
#else
    // Enables the safe-move-constructor idiom without C++11 move constructors
    struct AbstractBuilderMoveProxy {
        rti::xcdr::Stream owned_stream_;
        rti::xcdr::Stream *parent_stream_;
        AbstractBuilder *parent_builder_;
        unsigned char *begin_position_;
        unsigned char *bind_position_;
        bool initialize_on_add_;
#ifdef RTI_FLAT_DATA_NO_EXCEPTIONS
        bool failure_;
#endif
    };

    void move_from(AbstractBuilderMoveProxy& other)
    {
        detail::move_abstract_builder(*this, other);
    }

    void move_to(AbstractBuilderMoveProxy& other)
    {
        detail::move_abstract_builder(other, *this);
    }

    operator AbstractBuilderMoveProxy () throw() // move-constructor idiom
    {
        AbstractBuilderMoveProxy other;
        move_to(other);
        return other;
    }
private:
    AbstractBuilder(AbstractBuilder& other);
    AbstractBuilder& operator=(AbstractBuilder& other);    
#endif

protected:
    virtual ~AbstractBuilder()
    {
        finish_untyped_impl();
    }

    struct nested_tag_t {}; // disambiguate copy constructor
    
    /*i
     * @brief Creates a nested Builder to build a member or element
     * 
     * @param parent The Builder for the type that contains the member or element
     * this Builder builds.
     * 
     * @param alignment Specifies the alignment required by the concrete Builder.
     * Namely, aggregation and sequence builders require alignment of 4 for the 
     * DHeader and the sequence length, respectively. This alignment doesn't
     * reflect the alignment requirement of the elements, that's why arrays do
     * not require an alignment here. If no alignment is required, this parameter
     * must be zero. Concrete classes must provide a default value for alignment,
     * that indicates their requirement. This parameter can be overridden by
     * build_element_no_align to when we know we don't need to align.
     */
    AbstractBuilder(
            nested_tag_t, 
            AbstractBuilder& parent, 
            unsigned int alignment) 
        : /* owned_stream_ empty and unused */
          parent_stream_(&parent.stream()), /* work on the parent's stream */
          parent_builder_(&parent), 
          begin_position_(NULL),
          bind_position_(NULL),
          initialize_on_add_(parent.initialize_on_add_)
#ifdef RTI_FLAT_DATA_NO_EXCEPTIONS
          , failure_(false)
#endif          
    {
        if (alignment != 0) {
            if (!stream().align(alignment)) {
                RTI_FLAT_BUILDER_OUT_OF_RESOURCES_ERROR(return);
            }
        }
        begin_position_ = stream().current_position();
    }

    unsigned char * buffer()
    {
        return stream().buffer();
    }

    unsigned char * begin_position()
    {
        return begin_position_;
    }

    /*i
     * @brief Adds a fixed-size member or element
     * 
     * @return The offset to the member or element that was added. This offset
     * can be used to initialize it.
     */
    template <typename OffsetType>
    OffsetType add_element()
    {
        RTI_FLAT_BUILDER_CHECK_VALID(return OffsetType());
        RTI_FLAT_BUILDER_CHECK_NOT_BOUND(return OffsetType());

        offset_t member_size = OffsetType::serialized_size(0);
        unsigned char *pos = stream().current_position();
        
        if (!stream().skip(member_size)) {
            RTI_FLAT_BUILDER_OUT_OF_RESOURCES_ERROR(return OffsetType());
        }

        if (initialize_on_add_) {
            OffsetType offset(
                (SampleBase *) stream().buffer(), 
                detail::ptrdiff(pos, stream().buffer()));

            detail::final_offset_initializer<OffsetType>::initialize(offset);

            return offset;
        } else {
            return OffsetType(
                (SampleBase *) stream().buffer(), 
                detail::ptrdiff(pos, stream().buffer()));
        }
    }

    /*i
     * @brief Creates a nested Builder to build a variable-size member or element
     * 
     * @param stream_memento Subclasses using build_element() to implement
     * their own build method are required to provide a stream memento that
     * contains the position in the stream before any bytes related to this
     * member were added. Any error before the nested Builder is created will
     * cause the memento's destructor to roll back the Builder to its state
     * before this member was added. If the Builder can be created without errors
     * stream_mement.discard() is called, and its position is kept in case
     * the nested Builder is discarded (instead of finished), which also rolls
     * back the parent Builder to its previous state.
     * 
     * @post This Builder becomes "bound" until the returned Builder is finished.
     * While bound, this Builder can't be used to add or build more elements.
     * 
     * @return The Builder that allows building this member or element
     */
    template <typename NestedBuilder>
    NestedBuilder build_element(rti::xcdr::Stream::Memento& stream_memento)
    {
        RTI_FLAT_BUILDER_CHECK_VALID(return NestedBuilder());
        RTI_FLAT_BUILDER_CHECK_NOT_BOUND(return NestedBuilder());

        NestedBuilder nested_builder(nested_tag_t(), *this);
        RTI_FLAT_BUILDER_CHECK_CREATE_BUILDER(
                nested_builder, 
                return NestedBuilder());

        bind_position_ = stream_memento.discard();

        // uninit_use_in_call is not possible given how the constructor for
        // the NestedBuilder type is generated by rtiddsgen. The warning is
        // suppressed for performance reasons.
        // coverity[uninit_use_in_call : FALSE]
        return RTI_FLAT_MOVE_BUILDER(nested_builder);
    }

    template <typename NestedBuilder>
    NestedBuilder build_element_no_align(rti::xcdr::Stream::Memento& stream_memento)
    {
        RTI_FLAT_BUILDER_CHECK_VALID(return NestedBuilder());
        RTI_FLAT_BUILDER_CHECK_NOT_BOUND(return NestedBuilder());

        // By passing '0' to the builder constructor we override its default
        // argument which indicates its required alignment
        NestedBuilder nested_builder(nested_tag_t(), *this, 0);
        RTI_FLAT_BUILDER_CHECK_CREATE_BUILDER(
                nested_builder, 
                return NestedBuilder());

        bind_position_ = stream_memento.discard();

        // uninit_use_in_call is not possible given how the constructor for
        // the NestedBuilder type is generated by rtiddsgen. The warning is
        // suppressed for performance reasons.
        // coverity[uninit_use_in_call : FALSE]
        return RTI_FLAT_MOVE_BUILDER(nested_builder);
    }  

    /*i
     * @brief Returns the currently used number of bytes
     * 
     * The current size is the number of bytes that have been used to create
     * this sample by adding or building members.
     * 
     * When current_size() reaches capacity(), the Builder will fail to add
     * or build any additional member.
     * 
     * @see capacity().
     */
    unsigned int current_size()
    {
        return detail::ptrdiff(stream().current_position(), begin_position_);
    }    


    friend class AggregationBuilder; // to access finish_member()

    // Finishes this nested builder, updating the parent builder.
    //
    // This function doesn't throw exceptions and doesn't return a typed Offset
    // This function can be used in destructors to "silently" finish the builder
    void finish_untyped_impl()
    {
        if (!is_valid() || !is_nested()) {
            return;
        }

        parent_builder_->finish_member();
        invalidate();
    }

protected:
    /*i
     * @brief Complete the building of a nested member
     * 
     * Concrete Builders must implement a finish() function with the following body:
     * 
     * RTI_FLAT_BUILDER_CHECK_CAN_FINISH(...);
     * // optionally, additonal work
     * return finish_impl<OffsetType>();
     * 
     * Destructors can directly call finish_untyped_impl(); 
     * 
     * When this is a nested Builder, this function indicates that this element
     * or member is complete.
     * 
     * This function is automatically called by the Builder destructor.
     * 
     * Concrete builders must override this function to return a typed Offset to
     * the element that was built.
     * 
     * @post This Builder is in an empty state and cannot be used further
     * 
     * @return The position in the buffer where this element ended.
     */
    template <typename OffsetType>
    OffsetType finish_impl()
    {
        RTI_FLAT_BUILDER_CHECK_VALID(return OffsetType());

        unsigned char *begin_pos = this->begin_position_;
        unsigned char *sample_base = stream().buffer();
        unsigned char *current_pos = stream().current_position();
        finish_untyped_impl();
    
        return OffsetType(
                reinterpret_cast<SampleBase *>(sample_base), // start of the top-level sample
                detail::ptrdiff(begin_pos, sample_base), // absoute offset to the member
                detail::ptrdiff(current_pos, begin_pos)); // size of the member
    }

public:
    void discard()
    {
        RTI_FLAT_BUILDER_CHECK_VALID(return);
        RTI_FLAT_BUILDER_CHECK_CAN_FINISH(return);

        parent_builder_->discard_member();
        invalidate();
    }

    bool is_nested() const
    {
        return parent_builder_ != NULL;
    }

    bool is_valid() const
    {
        return begin_position_ != NULL;
    }

    rti::xcdr::length_t capacity() const
    {
        return stream().total_size();
    }

protected:
    // Makes this Builder invalid after finish(); discard(); finish_sample();
    // and, when exceptions are not enabled (traditional C++ API), after an
    // error during construction
    void invalidate()
    {
        parent_stream_ = NULL;
        parent_builder_ = NULL;
        bind_position_ = NULL;
        begin_position_ = NULL;
    }

    // This function is called by a nested Builder when it has finished building
    // an element
    virtual void finish_member() // noexcept
    {
        if (!is_valid()) {
            return;
        }

        bind_position_ = NULL;
    }

    void discard_member()
    {
        RTI_FLAT_BUILDER_CHECK_VALID(return);

        stream().current_position(bind_position_);
        bind_position_ = NULL;
    }

    rti::xcdr::Stream& stream()
    {
        if (parent_stream_ != NULL) {
            return *parent_stream_;
        } else {
            return owned_stream_;
        }
    }

    const rti::xcdr::Stream& stream() const
    {
        if (parent_stream_ != NULL) {
            return *parent_stream_;
        } else {
            return owned_stream_;
        }
    }

private:
    rti::xcdr::Stream owned_stream_;
    rti::xcdr::Stream *parent_stream_;
    AbstractBuilder *parent_builder_;
    unsigned char *begin_position_;
    unsigned char *bind_position_;
    bool initialize_on_add_;

#ifdef RTI_FLAT_DATA_NO_EXCEPTIONS
public:
    bool check_failure()
    {
        bool failure = failure_;
        failure_ = false;
        return failure;
    }
protected:
    void set_failure()
    {
        failure_ = true;
    }
private:
    bool failure_;
#endif


};

} }

#endif // RTI_DDS_FLAT_BUILDER_HPP_