VLink  2.3.0
A high-performance communication middleware
fast_buffer.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 fast_buffer.h
26  * @brief Platform-independent buffer with a @c Header and a pointer-free wire envelope.
27  *
28  * @details
29  * @c FastBuffer pairs sequencing metadata with a reference to CPU, device or
30  * other provider-managed storage. The first construction obtains the singleton
31  * @c FastBufferManager; @c VLINK_FASTBUFFER_PLUGIN selects a provider, while an
32  * unset or empty variable selects ordinary CPU memory.
33  *
34  * | Operation | Payload behavior | Ownership |
35  * | ---------------------- | ---------------------------------- | --------------------------- |
36  * | @c create() | Allocates in the selected domain | Owns one provider reference |
37  * | Copy / @c deep_copy() | Copies through the provider | Owns independent storage |
38  * | @c shallow_copy() | No payload copy | Retains the same allocation |
39  * | Move / @c move_copy() | No payload copy | Transfers the reference |
40  * | Shared deserialization | Imports a sharing descriptor | Owns one import reference |
41  * | Host deserialization | Copies bytes into provider storage | Owns independent storage |
42  *
43  * @par Memory access
44  * @code
45  * FastBuffer
46  * +----------------+
47  * | Header |
48  * | local address -+----> CPU / GPU / DMA / virtual storage
49  * | core ref | |
50  * +----------------+ |
51  * | |
52  * +-- map()/unmap() <--- host-accessible mapping
53  * |
54  * +-- copy_to_host() ---> ordinary CPU Bytes
55  * @endcode
56  * @c address() is an opaque local address, not a CPU pointer. Use @c map()
57  * only when supported and pair it with @c unmap(); device-only allocations
58  * require explicit host transfer. Copies and synchronization use the provider.
59  *
60  * @par Memory layout
61  * @code
62  * Offset Size Field (64-bit targets)
63  * ------ ---- ----------------------------------
64  * 0 40 Header header
65  * 40 32 Buffer buffer_
66  * 72 8 MetadataBuffer* metadata_
67  * 80 8 uint64_t reserved_buf_
68  * 88 8 uint64_t reserved_buf2_
69  * ------ ---- ----------------------------------
70  * Total 96 bytes (alignas 8)
71  * @endcode
72  *
73  * @par Wire format
74  * The fixed wire header is serialized independently of the local @c Metadata
75  * view and C++ object. Pointers, ownership references and process-local device indices
76  * never travel in the envelope. Byte order follows the other zero-copy types.
77  * @code
78  * Metadata offset Size Field
79  * --------------- ---- ----------------------------------
80  * 0 40 Header header
81  * 40 8 uint64_t size
82  * 48 8 uint64_t protocol
83  * 56 1 Storage storage
84  * 57 1 MemoryType memory_type
85  * 58 6 uint8_t reserved1[6] (zero)
86  * 64 8 uint64_t metadata_size
87  * 72 16 uint64_t reserved[2]
88  * --------------- ---- ----------------------------------
89  * Total 88 bytes (alignas 8)
90  *
91  * [ magic_begin (4) | version (4) | wire header (88) | metadata (M) | payload (N) | magic_end (4) ]
92  * @endcode
93  *
94  * | Wire storage | Payload | Availability |
95  * | ------------ | --------------------------------- | ----------------------------------- |
96  * | Shared | Control block name and generation | Compatible provider and live source |
97  * | Host | Complete CPU-readable bytes | No sharing descriptor required |
98  *
99  * @c operator>> uses a sharing descriptor when supported, otherwise host bytes. A shared
100  * descriptor names the allocation and its generation; importing after the owner reused
101  * (@c FastBufferPool) or retired the allocation fails as expired, and the message is dropped.
102  * @c MessageParser reads and prints metadata without importing the allocation.
103  * Variable-length metadata is ordinary CPU storage, separate from the provider
104  * payload. @c set_metadata() copies input bytes or adopts an owned rvalue;
105  * @c shallow_copy() retains that metadata allocation without copying its contents.
106  *
107  * @par Example
108  * @code
109  * vlink::zerocopy::FastBuffer buffer;
110  * const auto input = vlink::Bytes::create(1024);
111  * if (buffer.create(input.size()) && buffer.copy_from_host(input)) {
112  * vlink::Bytes wire;
113  * if (buffer >> wire) {
114  * vlink::zerocopy::FastBuffer received;
115  * if (received << wire) {
116  * vlink::Bytes output;
117  * const bool copied = received.copy_to_host(output);
118  * }
119  * }
120  * }
121  * @endcode
122  * Publishers recycle allocations through @ref vlink::zerocopy::FastBufferPool; the sharing contract is
123  * defined by @ref vlink::FastBufferPluginInterface and @ref vlink::FastBufferManager.
124  */
125 
126 #pragma once
127 
128 #include <cstddef>
129 #include <cstdint>
130 
131 #include "../base/bytes.h"
132 #include "./header.h"
133 
134 namespace vlink {
135 
136 namespace zerocopy {
137 
138 class FastBufferPool;
139 
140 /**
141  * @struct FastBuffer
142  * @brief Holds a local memory address and an owned provider reference.
143  *
144  * @details
145  * Construction initializes @c FastBufferManager; operations obtain its provider without storing a plugin pointer.
146  * Release buffers before manager shutdown. Copy construction and assignment
147  * deep-copy through the provider; @c shallow_copy explicitly retains the same allocation without payload
148  * copying. A retained reference survives its source object.
149  * Moving transfers the reference and leaves the source empty.
150  *
151  * The wire format is [magic (4), version (4), fixed header (88), metadata (M), payload (N), end magic (4)] in the same
152  * native byte order as other zero-copy containers. Shared payloads name a control block, not local
153  * addresses. Host payloads contain actual bytes and are copied into provider storage on deserialization.
154  * Local C++ object memory, plugin references and device indices are never serialized.
155  *
156  * Releasing the last local reference of an exported allocation never waits for importers.
157  * Sharing lifetime follows @ref vlink::FastBufferPluginInterface.
158  */
159 struct VLINK_EXPORT_AND_ALIGNED(8) FastBuffer final {
160  /**
161  * @enum MemoryType
162  * @brief Allocation domain; unsupported requests fail instead of changing domains.
163  */
164  enum MemoryType : uint8_t {
165  kMemoryDefault = 0, ///< Provider default.
166  kMemoryHost = 1, ///< CPU memory, including provider-managed pinned memory.
167  kMemoryDevice = 2, ///< Device-local memory.
168  kMemoryShared = 3, ///< Memory shared by CPU and devices or processes.
169  kMemoryDmaBuf = 4, ///< DMA-BUF resource, possibly without a permanent mapping.
170  kMemoryVirtual = 5, ///< Provider-managed virtual memory.
171  };
172 
173  /**
174  * @struct Config
175  * @brief Allocation request independent of image, tensor and vendor APIs.
176  */
177  struct Config final {
178  MemoryType memory_type{kMemoryDefault}; ///< Requested allocation domain.
179  int32_t device{-1}; ///< Provider-local device, or the default.
180  };
181 
182  /**
183  * @enum Access
184  * @brief CPU access direction for map/unmap and cache maintenance.
185  */
186  enum Access : uint8_t {
187  kRead = 1, ///< CPU reads.
188  kWrite = 2, ///< CPU writes.
189  kReadWrite = 3, ///< CPU reads and writes.
190  };
191 
192  /**
193  * @struct Buffer
194  * @brief One local reference to a contiguous allocation in the provider's address space.
195  */
196  struct Buffer final {
197  uint8_t* data{nullptr}; ///< Optional local address; CPU accessibility requires map().
198  size_t size{0}; ///< Addressable byte count.
199  void* handle{nullptr}; ///< Core reference in FastBuffer; optional SDK state in interface calls.
200  int32_t device{-1}; ///< Plugin-local device index; never interpreted across processes.
201  MemoryType memory_type{kMemoryDefault}; ///< Actual allocation domain.
202  };
203 
204  /**
205  * @enum Storage
206  * @brief Meaning of the wire payload.
207  */
208  enum Storage : uint8_t {
209  kStorageShared = 1, ///< Runtime sharing descriptor; requires a compatible live provider.
210  kStorageHost = 2, ///< Inline host bytes; contains no runtime sharing handle.
211  };
212 
213  /**
214  * @struct Metadata
215  * @brief Decoded metadata and a variable-length CPU buffer, readable without loading a plugin.
216  *
217  * @details
218  * @c read_metadata() borrows the variable-length buffer from its input wire
219  * storage. Keep that input alive while reading @c buffer. This C++ view is
220  * not copied directly to the wire.
221  */
222  struct Metadata final {
223  Header header; ///< Sequencing and timestamps.
224  uint64_t size{0}; ///< Actual payload size in bytes, excluding any descriptor.
225  uint64_t protocol{0}; ///< Descriptor protocol ID; zero for host storage.
226  Storage storage{kStorageShared}; ///< Shared descriptor or inline host data.
227  MemoryType memory_type{kMemoryDefault}; ///< Producer allocation domain.
228  uint64_t reserved[2]{}; ///< 16 reserved bytes, preserved across serialization and copies.
229  Bytes buffer; ///< Variable-length CPU metadata, separate from the provider payload.
230  };
231 
232  /**
233  * @brief Obtains the singleton provider and constructs an empty buffer.
234  */
235  FastBuffer();
236 
237  /**
238  * @brief Releases this reference after local device use completes.
239  */
240  ~FastBuffer() noexcept;
241 
242  /**
243  * @brief Deep-copies @p target on the device; failure leaves this buffer empty.
244  *
245  * @param target Source buffer.
246  */
247  FastBuffer(const FastBuffer& target) noexcept;
248 
249  /**
250  * @brief Transfers @p target's reference and metadata.
251  *
252  * @param target Source buffer, left empty.
253  */
254  FastBuffer(FastBuffer&& target) noexcept;
255 
256  /**
257  * @brief Deep-copy-assigns @p target; failure preserves this buffer.
258  *
259  * @param target Source buffer.
260  *
261  * @return This buffer.
262  */
263  FastBuffer& operator=(const FastBuffer& target) noexcept;
264 
265  /**
266  * @brief Move-assigns @p target; self-assignment is a no-op.
267  *
268  * @param target Source buffer, left empty.
269  *
270  * @return This buffer.
271  */
272  FastBuffer& operator=(FastBuffer&& target) noexcept;
273 
274  /**
275  * @brief Imports shared storage or uploads host storage.
276  *
277  * @param bytes Complete wire envelope.
278  *
279  * @return Whether decoding succeeded; failure preserves this buffer.
280  */
281  [[nodiscard]] bool operator<<(const Bytes& bytes) noexcept;
282 
283  /**
284  * @brief Serializes a sharing descriptor, or host bytes when sharing is unavailable.
285  *
286  * @param bytes Output storage, reused when exactly sized; incompatible loans are rejected.
287  *
288  * @return Whether serialization succeeded; shared mode does not copy the payload.
289  */
290  [[nodiscard]] bool operator>>(Bytes& bytes) const noexcept;
291 
292  /**
293  * @brief Validates the complete wire envelope without loading a plugin.
294  *
295  * @param bytes Wire bytes.
296  *
297  * @return Whether metadata and payload lengths are valid.
298  */
299  [[nodiscard]] static bool check_valid(const Bytes& bytes) noexcept;
300 
301  /**
302  * @brief Reads validated metadata without importing device memory.
303  *
304  * @param bytes Complete wire envelope.
305  * @param metadata Output metadata, unchanged on failure.
306  *
307  * @return Whether the envelope is valid.
308  */
309  [[nodiscard]] static bool read_metadata(const Bytes& bytes, Metadata& metadata) noexcept;
310 
311  /**
312  * @brief Returns the selected wire size.
313  *
314  * @return Envelope plus descriptor or host bytes, or zero when empty.
315  */
316  [[nodiscard]] size_t get_serialized_size() const noexcept;
317 
318  /**
319  * @brief Reports whether this object holds a live memory reference.
320  *
321  * @return Whether the size and core reference are valid; a mapping is not required.
322  */
323  [[nodiscard]] bool is_valid() const noexcept;
324 
325  /**
326  * @brief Allocates an uninitialised buffer in the provider's default memory domain.
327  *
328  * @param size Nonzero byte count.
329  * @param device Plugin-local device index, or -1 for the default.
330  *
331  * @return Whether allocation succeeded; failure preserves this buffer.
332  */
333  [[nodiscard]] bool create(size_t size, int32_t device = -1) noexcept;
334 
335  /**
336  * @brief Allocates memory in the requested domain.
337  *
338  * @param size Nonzero byte count.
339  * @param config Memory type and provider-local device.
340  *
341  * @return Whether the provider supports and satisfies the request.
342  */
343  [[nodiscard]] bool create(size_t size, const Config& config) noexcept;
344 
345  /**
346  * @brief Retains @p target's allocation without copying its payload.
347  *
348  * @param target Source buffer.
349  *
350  * @return Whether an independent reference was acquired; self-copy returns false.
351  */
352  [[nodiscard]] bool shallow_copy(const FastBuffer& target) noexcept;
353 
354  /**
355  * @brief Allocates and copies @p target through its provider.
356  *
357  * @param target Source buffer.
358  *
359  * @return Whether copying succeeded; self-copy returns false.
360  */
361  [[nodiscard]] bool deep_copy(const FastBuffer& target) noexcept;
362 
363  /**
364  * @brief Transfers @p target's reference and metadata.
365  *
366  * @param target Source buffer, left empty.
367  *
368  * @return Whether a move occurred; self-move returns false.
369  */
370  bool move_copy(FastBuffer& target) noexcept;
371 
372  /**
373  * @brief Releases the memory reference and resets metadata.
374  */
375  void clear() noexcept;
376 
377  /**
378  * @brief Waits for previously submitted local device work.
379  *
380  * @return Whether synchronization succeeded.
381  */
382  [[nodiscard]] bool synchronize() const noexcept;
383 
384  /**
385  * @brief Copies the full payload to host storage.
386  *
387  * @param bytes Destination host buffer, reused when exactly sized.
388  *
389  * @return Whether the synchronous read completed.
390  */
391  [[nodiscard]] bool copy_to_host(Bytes& bytes) const noexcept;
392 
393  /**
394  * @brief Writes the full payload from equally sized host bytes.
395  *
396  * @param bytes Source host storage.
397  *
398  * @return Whether the synchronous write completed.
399  */
400  [[nodiscard]] bool copy_from_host(const Bytes& bytes) noexcept;
401 
402  /**
403  * @brief Returns the optional process-local address as an opaque integer.
404  *
405  * @return Address value, or zero when unmapped/empty; use map() for CPU access.
406  */
407  [[nodiscard]] uintptr_t address() const noexcept;
408 
409  /**
410  * @brief Returns the payload byte count.
411  *
412  * @return Zero when empty.
413  */
414  [[nodiscard]] size_t size() const noexcept;
415 
416  /**
417  * @brief Returns the plugin-local device index.
418  *
419  * @return Device index, or -1 when empty.
420  */
421  [[nodiscard]] int32_t device() const noexcept;
422 
423  /**
424  * @brief Returns the actual allocation domain.
425  *
426  * @return Provider-reported memory type.
427  */
428  [[nodiscard]] MemoryType memory_type() const noexcept;
429 
430  /**
431  * @brief Reports whether this object owns a plugin reference.
432  *
433  * @return Whether destruction must release a reference, including retained/imported buffers.
434  */
435  [[nodiscard]] bool is_owner() const noexcept;
436 
437  /**
438  * @brief Maps the buffer for CPU access and performs required cache maintenance.
439  *
440  * @param access Read, write or read-write access.
441  * @return Host pointer, or nullptr when mapping is unsupported or failed.
442  *
443  * @note Pair successful calls with @c unmap(). Finish external device work before mapping.
444  */
445  [[nodiscard]] uint8_t* map(Access access) const noexcept;
446 
447  /**
448  * @brief Ends CPU access and publishes CPU writes when required.
449  *
450  * @param access Access mode used for the matching @c map().
451  * @return Whether unmapping/cache maintenance completed.
452  */
453  [[nodiscard]] bool unmap(Access access) const noexcept;
454 
455  /**
456  * @brief Returns a borrowed provider-native resource description.
457  *
458  * @return Provider-defined native object, valid while this reference is alive.
459  */
460  [[nodiscard]] const void* native_handle() const noexcept;
461 
462  /**
463  * @brief Retains an externally supplied provider-native resource.
464  *
465  * @param handle Native object matching the loaded provider's documented type.
466  * @return Whether an independent reference was acquired; unsupported imports return false.
467  */
468  [[nodiscard]] bool import_native(const void* handle) noexcept;
469 
470  /**
471  * @brief Copies variable-length CPU metadata into owned storage.
472  *
473  * @param bytes Metadata bytes; empty input clears the metadata.
474  *
475  * @return Whether copying succeeded; failure preserves the previous metadata.
476  */
477  [[nodiscard]] bool set_metadata(const Bytes& bytes) noexcept;
478 
479  /**
480  * @brief Adopts owned metadata bytes; borrowed input is copied into owned storage.
481  *
482  * @param bytes Metadata bytes moved on successful adoption.
483  *
484  * @return Whether metadata storage was acquired.
485  */
486  [[nodiscard]] bool set_metadata(Bytes&& bytes) noexcept;
487 
488  /**
489  * @brief Returns the variable-length CPU metadata.
490  *
491  * @return Borrowed read-only bytes, valid until metadata replacement or destruction.
492  */
493  [[nodiscard]] const Bytes& get_metadata() const noexcept;
494 
495  /**
496  * @brief Returns the first reserved field.
497  *
498  * @return Reference to @c reserved_buf_.
499  */
500  uint64_t& get_reserved() noexcept { return reserved_buf_; }
501 
502  /**
503  * @brief Returns the second reserved field.
504  *
505  * @return Reference to @c reserved_buf2_.
506  */
507  uint64_t& get_reserved2() noexcept { return reserved_buf2_; }
508 
509  Header header; ///< Sequencing and timestamp metadata prefix.
510 
511  static constexpr bool kZerocopyTypes{true}; ///< Serializer zero-copy schema marker.
512 
513  private:
514  friend class FastBufferPool;
515 
516  struct MetadataBuffer;
517 
518  static MetadataBuffer* copy_metadata(const Bytes& bytes) noexcept;
519 
520  void clear_metadata() noexcept;
521 
522  Buffer buffer_;
523  MetadataBuffer* metadata_{nullptr};
524  uint64_t reserved_buf_{0};
525  uint64_t reserved_buf2_{0};
526 
527  static constexpr uint32_t kMagicNumberBegin{0x98B7F1BA};
528  static constexpr uint32_t kMagicNumberEnd{0x98B7F1BF};
529 };
530 
531 } // namespace zerocopy
532 
533 } // namespace vlink
Fixed-size timestamp and sequencing prefix embedded by every VLink zero-copy container.
Holds a local memory address and an owned provider reference.
Definition: fast_buffer.h:138
40-byte timestamp / sequencing metadata prefix shared by all zero-copy containers.