intra_data.h

浏览该文件的文档.

/*
 * Copyright (C) 2026 by Thun Lu. All rights reserved.
 * Author: Thun Lu <thun.lu@zohomail.cn>
 * Repo:   https://github.com/thun-res/vlink
 *  _    __   __      _           __
 * | |  / /  / /     (_) ____    / /__
 * | | / /  / /     / / / __ \  / //_/
 * | |/ /  / /___  / / / / / / / ,<
 * |___/  /_____/ /_/ /_/ /_/ /_/|_|
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
/**
 * @file intra_data.h
 * @brief Zero-serialisation in-process message container for intra:// transport.
 *
 * @details
 * @c IntraData is the zero-copy message type used exclusively on the
 * @c intra:// transport, where publisher and subscriber reside in the same process.
 * Instead of serialising a message to @c Bytes and immediately deserialising it
 * on the other side, a @c shared_ptr to the payload object is passed directly.
 *
 * @par Usage Pattern
 * The @c VLINK_INTRA_DATA_DECLARE(target_type, declare_name) macro generates two
 * types for a given VLink message type @c T:
 * - @c declare_nameType -- concrete @c IntraDataType subclass holding a @c T value
 *   plus serialisation/deserialisation helpers.
 * - @c declare_name -- a @c std::shared_ptr<declare_nameType> wrapper with a static
 *   @c create() factory and implicit conversions from the base @c shared_ptr.
 *
 * @par Example
 * @code
 * // Declare once (typically in a generated or per-type header):
 * VLINK_INTRA_DATA_DECLARE(MyProtoMsg, MyProtoIntra)
 *
 * // In Publisher:
 * auto data = MyProtoIntra::create();
 * data->value.set_field(42);
 * pub.publish_intra(data);  // zero-copy path
 *
 * // In Subscriber:
 * sub.listen([](const MyProtoIntra& intra) {
 *   // use typed->value directly
 * });
 * @endcode
 *
 * @note @c IntraData messages are only supported on @c intra:// topics.  Attempting
 *       to call @c write(IntraData) on a non-intra @c PublisherImpl logs a warning
 *       and returns @c false.
 */
 
#pragma once
 
#include <memory>
#include <string>
 
#include "../serializer.h"
#include "./types.h"
 
namespace vlink {
 
/**
 * @struct IntraDataType
 * @brief Polymorphic base for all typed in-process message containers.
 *
 * @details
 * Concrete subtypes generated by @c VLINK_INTRA_DATA_DECLARE carry the actual
 * message value and implement @c operator<< / @c operator>> for on-demand
 * serialisation when the message must cross a transport boundary.
 */
struct IntraDataType {
  IntraDataType() = default;
  virtual ~IntraDataType() = default;
};
 
/**
 * @brief Shared-ownership handle for an @c IntraDataType payload.
 *
 * @details
 * Passed between the publisher and subscriber in the same process by reference
 * counting, avoiding any serialisation or data copy.  Downcast to the concrete
 * @c declareNameType via @c std::static_pointer_cast<> or use the typed
 * @c declare_name wrapper generated by @c VLINK_INTRA_DATA_DECLARE.
 */
using IntraData = std::shared_ptr<IntraDataType>;
 
}  // namespace vlink
 
/**
 * @def VLINK_INTRA_DATA_DECLARE
 * @brief Generates a typed in-process message container pair.
 *
 * @details
 * Expands to two declarations:
 *
 * -# @c declare_nameType -- a concrete @c IntraDataType subclass with:
 *    - @c target_type value -- the message payload.
 *    - @c static constexpr Serializer::Type kValueType -- compile-time type tag.
 *    - @c bool operator<<(const Bytes&) -- deserialise @c Bytes into @c value.
 *    - @c bool operator>>(Bytes&) const -- serialise @c value into @c Bytes.
 *    - @c size_t get_serialized_size() const -- byte count needed for serialisation.
 *    - @c static std::string get_serialized_type() -- type name string.
 *    - A @c static_assert ensuring @c target_type is a supported serialiser type.
 *
 * -# @c declare_name -- a @c std::shared_ptr<declare_nameType> subclass with:
 *    - Constructors and conversions from the base @c shared_ptr.
 *    - @c static declare_name create() -- factory returning a heap-allocated instance.
 *
 * @param target_type   The VLink message type (must be a supported @c Serializer::Type).
 * @param declare_name  The name to give the generated container types.
 */
#define VLINK_INTRA_DATA_DECLARE(target_type, declare_name)                                              \
  struct declare_name##Type : public vlink::IntraDataType {                                              \
    target_type value;                                                                                   \
                                                                                                         \
    static constexpr vlink::Serializer::Type kValueType = vlink::Serializer::get_type_of<target_type>(); \
                                                                                                         \
    static_assert(vlink::Serializer::is_supported(kValueType),                                           \
                  "VLINK_INTRA_DATA_DECLARE(target_type) is not a supported Serializer type.");          \
                                                                                                         \
    bool operator<<(const vlink::Bytes& bytes) noexcept {                                                \
      return vlink::Serializer::deserialize<kValueType>(bytes, value);                                   \
    }                                                                                                    \
                                                                                                         \
    bool operator>>(vlink::Bytes& bytes) const noexcept {                                                \
      return vlink::Serializer::serialize<kValueType>(value, bytes);                                     \
    }                                                                                                    \
                                                                                                         \
    [[nodiscard]] size_t get_serialized_size() const noexcept {                                          \
      return vlink::Serializer::get_serialized_size<kValueType>(value);                                  \
    }                                                                                                    \
                                                                                                         \
    [[nodiscard]] static std::string get_serialized_type() noexcept {                                    \
      return vlink::Serializer::get_serialized_type<kValueType, target_type>();                          \
    }                                                                                                    \
                                                                                                         \
    [[nodiscard]] static constexpr vlink::SchemaType get_schema_type() noexcept {                        \
      return vlink::Serializer::get_schema_type<kValueType, target_type>();                              \
    }                                                                                                    \
  };                                                                                                     \
                                                                                                         \
  struct declare_name : public std::shared_ptr<declare_name##Type> {                                     \
    using Base = std::shared_ptr<declare_name##Type>;                                                    \
    using Base::Base;                                                                                    \
                                                                                                         \
    /*NOLINTBEGIN*/                                                                                      \
    declare_name() noexcept = default;                                                                   \
                                                                                                         \
    declare_name(Base&& other) noexcept : Base(std::move(other)) {}                                      \
                                                                                                         \
    declare_name(const Base& other) noexcept : Base(other) {}                                            \
                                                                                                         \
    [[nodiscard]] static declare_name create() noexcept {                                                \
      return declare_name(std::make_shared<declare_name##Type>());                                       \
    }                                                                                                    \
    /*NOLINTEND*/                                                                                        \
  };