VLink  2.3.0
A high-performance communication middleware
dynamic_data.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2026 by Thun Lu. All rights reserved.
3  * Author: Thun Lu <thun.lu@zohomail.cn>
4  * Repo: https://github.com/thun-res/vlink
5  * _ __ __ _ __
6  * | | / / / / (_) ____ / /__
7  * | | / / / / / / / __ \ / //_/
8  * | |/ / / /___ / / / / / / / ,<
9  * |___/ /_____/ /_/ /_/ /_/ /_/|_|
10  *
11  * Licensed under the Apache License, Version 2.0 (the "License");
12  * you may not use this file except in compliance with the License.
13  * You may obtain a copy of the License at
14  *
15  * http://www.apache.org/licenses/LICENSE-2.0
16  *
17  * Unless required by applicable law or agreed to in writing, software
18  * distributed under the License is distributed on an "AS IS" BASIS,
19  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20  * See the License for the specific language governing permissions and
21  * limitations under the License.
22  */
23 
24 /**
25  * @file dynamic_data.h
26  * @brief Self-describing serialised payload tagged with an inline type name.
27  *
28  * @details
29  * @c DynamicData carries a serialised VLink-compatible message together with a short
30  * type-name tag inside a single @c Bytes buffer. The first @c kOffset = 20 bytes of the
31  * buffer hold the type name (NUL-padded), and the remainder holds the payload as produced
32  * by @c Serializer. This layout lets transports route, log and inspect a payload without
33  * knowing its concrete C++ type at compile time -- the recipient picks the matching
34  * deserialiser at run time using the embedded tag.
35  *
36  * Supported dynamic categories (chosen automatically by @c Serializer):
37  *
38  * | Category | Examples | Notes |
39  * | ---------- | --------------------------------- | ------------------------------------------ |
40  * | Protobuf | @c MyProto, @c std::shared_ptr<P> | Encoded with the message's wire format |
41  * | FlatBuffer | @c MyTable, builder types | Native table or completed builder payload |
42  * | POD/Std | @c int, @c struct Foo (trivial) | Standard layout copy |
43  * | Bytes | @c vlink::Bytes | Stored verbatim |
44  * | String | @c std::string | Stored as raw string bytes |
45  * | Chars | @c char[N], @c const char* | Stored without the trailing NUL |
46  * | SOME/IP | Macro-declared structures | Stored as raw SOME/IP payload |
47  * | Custom | Types with explicit @c Serializer | User-provided serialise/deserialise hooks |
48  *
49  * Nested @c DynamicData and CDR are rejected for both directions. @c load() also rejects
50  * non-owning FlatBuffers table pointers and POD pointers because those serialization paths
51  * cannot reserve the inline type-name prefix. The type-name literal (including its trailing
52  * NUL) must fit in fewer than @c kOffset bytes.
53  *
54  * Buffer layout:
55  *
56  * @verbatim
57  * +----------------------------+-----------------------------------------+
58  * | type name (20 bytes max) | serialised payload |
59  * +----------------------------+-----------------------------------------+
60  * ^ ^
61  * data_.real_data() data_.real_data() + kOffset
62  * @endverbatim
63  *
64  * @par Example
65  * @code
66  * vlink::DynamicData dd;
67  * MyProtoMsg msg;
68  * msg.set_value(42);
69  * dd.load("MyProtoMsg", msg); // serialise + tag
70  *
71  * // Send over any transport that handles vlink::Bytes:
72  * vlink::Bytes wire;
73  * dd >> wire;
74  *
75  * vlink::DynamicData received;
76  * received << wire; // recover the tagged blob
77  * if (received.get_type() == "MyProtoMsg") {
78  * MyProtoMsg out = received.as<MyProtoMsg>(); // deserialise
79  * (void)out;
80  * }
81  * @endcode
82  */
83 
84 #pragma once
85 
86 #include <memory>
87 #include <string_view>
88 #include <utility>
89 
90 #include "../serializer.h"
91 
92 namespace vlink {
93 
94 /**
95  * @class DynamicData
96  * @brief Type-erased wrapper that pairs an inline type name with a serialised payload.
97  *
98  * @details
99  * Stores its payload in an internal @c Bytes buffer; the first @c kOffset bytes are
100  * reserved for the type name and exposed through @c get_type() as a @c string_view.
101  * Copy and move operations rebind the view to the local buffer to avoid dangling.
102  */
104  public:
105  /**
106  * @brief Builds an empty container with no buffer and no type tag.
107  */
109 
110  /**
111  * @brief Copies the buffer and rebinds the local type view to point into the new buffer.
112  */
113  DynamicData(const DynamicData& target);
114 
115  /**
116  * @brief Adopts the source buffer and rebinds the type view to point at this object's storage.
117  *
118  * @details
119  * The moved-from object is left in an empty state with no payload and no type tag.
120  */
121  DynamicData(DynamicData&& target) noexcept;
122 
123  /**
124  * @brief Copy-assignment that rebinds the local type view to point into the new buffer.
125  */
127 
128  /**
129  * @brief Move-assignment that rebinds the local type view and empties the source.
130  */
131  DynamicData& operator=(DynamicData&& target) noexcept;
132 
133  /**
134  * @brief Serialises @p t under the type tag @p type into the internal buffer.
135  *
136  * @details
137  * The type literal (including its trailing NUL) must be shorter than @c kOffset, which
138  * is checked at compile time. On serialiser failure the container is reset to empty
139  * and an error is logged.
140  *
141  * @tparam SizeT Length of the type-name string literal including the NUL terminator.
142  * @tparam T Source message type (must be supported by @c Serializer).
143  * @param type String literal containing the type-name tag.
144  * @param t Message instance to serialise.
145  * @return Reference to @c *this for chaining.
146  */
147  template <uint8_t SizeT, typename T>
148  DynamicData& load(const char (&type)[SizeT], const T& t);
149 
150  /**
151  * @brief Deserialises the stored payload into @p t.
152  *
153  * @details
154  * Fails when the container is empty or the @c Serializer cannot decode the buffer
155  * (for example because @p T is incompatible with the embedded payload).
156  *
157  * @tparam T Destination type.
158  * @param t Output reference populated on success.
159  * @return @c true on success; @c false otherwise.
160  */
161  template <typename T>
162  bool convert(T& t) const;
163 
164  /**
165  * @brief Default-constructs a @p T (or @c shared_ptr<T>) and decodes the payload into it.
166  *
167  * @tparam T Destination type; specialised for @c std::shared_ptr to allocate the inner object.
168  * @return Decoded instance, or a default-constructed @p T when decoding fails.
169  */
170  template <typename T>
171  [[nodiscard]] T as() const;
172 
173  /**
174  * @brief Returns the underlying @c Bytes buffer, including the embedded type name.
175  */
176  [[nodiscard]] const Bytes& get_data() const;
177 
178  /**
179  * @brief Returns the embedded type name as a view into the internal buffer.
180  *
181  * @details
182  * Only valid for the lifetime of this @c DynamicData instance.
183  */
184  [[nodiscard]] const std::string_view& get_type() const;
185 
186  /**
187  * @brief Returns whether the internal buffer is empty.
188  */
189  [[nodiscard]] bool is_empty() const;
190 
191  /**
192  * @brief Byte-equality comparison.
193  *
194  * @return @c true when both buffers hold identical bytes.
195  */
196  [[nodiscard]] bool operator==(const DynamicData& target) const;
197 
198  /**
199  * @brief Byte-inequality comparison.
200  */
201  [[nodiscard]] bool operator!=(const DynamicData& target) const;
202 
203  /**
204  * @brief Compile-time trait used by @c Serializer to detect @c DynamicData specialisations.
205  *
206  * @return Always @c true.
207  */
208  [[nodiscard]] static constexpr bool is_vlink_dynamic_data();
209 
210  /**
211  * @brief Returns the byte offset at which the serialised payload begins (= @c kOffset).
212  */
213  [[nodiscard]] static constexpr uint8_t get_offset();
214 
215  /**
216  * @brief Reconstructs the container from a wire-format @c Bytes blob.
217  *
218  * @param bytes Wire blob previously produced by @c operator>>.
219  * @return @c true on success.
220  */
221  bool operator<<(const Bytes& bytes) noexcept;
222 
223  /**
224  * @brief Emits the container as a wire-format @c Bytes blob.
225  *
226  * @param bytes Destination buffer.
227  * @return @c true on success; @c false when the internal buffer is empty, non-owning,
228  * or does not carry the reserved prefix.
229  */
230  bool operator>>(Bytes& bytes) const noexcept;
231 
232  private:
233  void refresh_type_view(size_t type_size) noexcept;
234 
235  static constexpr uint8_t kOffset{20};
236  Bytes data_;
237  std::string_view type_;
238 };
239 
240 ////////////////////////////////////////////////////////////////
241 /// Details
242 ////////////////////////////////////////////////////////////////
243 
244 template <uint8_t SizeT, typename T>
245 inline DynamicData& DynamicData::load(const char (&type)[SizeT], const T& t) {
246  constexpr Serializer::Type kSerializerType = Serializer::get_type_of<T>();
247 
248  static_assert(SizeT < get_offset(), "DynamicData name out of size.");
249  static_assert(!Serializer::is_dynamic_type<T>(), "DynamicData can not serialize self.");
250  static_assert(!Serializer::is_cdr_type<T>(), "DynamicData can not serialize cdr data.");
251  static_assert(kSerializerType != Serializer::kFlatPtrType && kSerializerType != Serializer::kStandardPtrType,
252  "DynamicData can not serialize non-owning pointer views.");
253 
254  Bytes next_data;
255  bool ret = Serializer::serialize<kSerializerType>(t, next_data, TransportType::kUnknown, get_offset());
256 
257  if VUNLIKELY (!ret || next_data.real_data() == nullptr) {
258  data_ = Bytes();
259  type_ = std::string_view();
260  VLOG_F("DynamicData serialize failed.");
261  return *this;
262  }
263 
264  data_ = std::move(next_data);
265 
266  if constexpr (SizeT > 0) {
267  std::memcpy(data_.real_data(), type, SizeT);
268 
269  if constexpr (SizeT < kOffset) {
270  std::memset(data_.real_data() + SizeT, 0, kOffset - SizeT);
271  }
272 
273  size_t name_len = SizeT;
274 
275  if (name_len > 0 && type[SizeT - 1] == '\0') {
276  name_len -= 1;
277  }
278 
279  type_ = std::string_view(reinterpret_cast<const char*>(data_.real_data()), name_len);
280  } else {
281  std::memset(data_.real_data(), 0, kOffset);
282  type_ = std::string_view();
283  }
284 
285  return *this;
286 }
287 
288 template <typename T>
289 inline bool DynamicData::convert(T& t) const {
290  static_assert(!Serializer::is_dynamic_type<T>(), "DynamicData can not deserialize self.");
291  static_assert(!Serializer::is_cdr_type<T>(), "DynamicData can not deserialize cdr data.");
292 
293  if VUNLIKELY (data_.empty()) {
294  return false;
295  }
296 
297  return Serializer::deserialize<Serializer::get_type_of<T>()>(data_, t, TransportType::kUnknown);
298 }
299 
300 template <typename T>
301 inline T DynamicData::as() const {
302  T t;
303 
304  if constexpr (Traits::IsSharedPtr<T>()) {
305  t = std::make_shared<typename T::element_type>();
306  }
307 
308  if VUNLIKELY (!convert(t)) {
309  VLOG_F("DynamicData deserialize failed.");
310  return T{};
311  }
312 
313  return t;
314 }
315 
316 inline constexpr bool DynamicData::is_vlink_dynamic_data() { return true; }
317 
318 inline constexpr uint8_t DynamicData::get_offset() { return kOffset; }
319 
320 } // namespace vlink
#define VLOG_F(...)
Definition: logger.h:906
#define VUNLIKELY(...)
Short alias for VLINK_UNLIKELY.
Definition: macros.h:292
#define VLINK_EXPORT
Definition: macros.h:81