VLink  2.3.0
A high-performance communication middleware
fast_buffer_plugin_interface.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_plugin_interface.h
26  * @brief Vendor-independent allocation and sharing contract for @c zerocopy::FastBuffer.
27  *
28  * @details
29  * @c FastBufferPluginInterface separates native allocation and host access from
30  * the platform that allocates the storage. Implementations may use ordinary or
31  * pinned CPU memory, device memory, shared memory, DMA-BUF or virtual allocations.
32  * Unsupported allocation domains and optional operations report failure.
33  *
34  * | Operation | Methods | Contract |
35  * | ------------------------ | ------------------------------------------------- | ------------------------------ |
36  * | Allocation and ownership | @c create(), @c release() | One owned reference per result |
37  * | CPU mapping | @c map(), @c unmap() | Explicit access/cache scope |
38  * | Native API integration | @c native_handle(), @c import_native() | Provider-defined local object |
39  * | Completion | @c synchronize() | Wait for tracked work |
40  * | Payload copy | @c copy(), @c copy_to_host(), @c copy_from_host() | Synchronous completion |
41  * | Descriptor transport | @c export_handle(), @c import_handle() | No local pointer on the wire |
42  * | Descriptor size | @c get_handle_size() | Per-allocation support |
43  * | Dead-owner cleanup | @c destroy_handle() | Named OS resources only |
44  *
45  * @par Sharing lifecycle
46  * @code
47  * Publishing process Subscribing process
48  * ------------------ -------------------
49  * pool acquire --> generation + 1
50  * |
51  * device/CPU writes
52  * |
53  * manager export -- name + generation --> manager import
54  * | claim reader slot, check generation
55  * | SDK import_handle()
56  * drop reference (never waits) |
57  * | device use or map/unmap
58  * next acquire: purge dead readers, |
59  * busy while live readers remain release(): SDK close, clear slot
60  * |
61  * final release: retire, free when the reader table is empty
62  * @endcode
63  *
64  * A @c zerocopy::FastBuffer::Buffer address belongs to its local process and address space.
65  * CPU callers must use @c map() or @c copy_to_host(); a non-null device address
66  * is not proof of CPU accessibility. Native objects and numeric file descriptors
67  * likewise require provider-specific import or OS handle transfer.
68  *
69  * @par Plugin registration
70  * @code
71  * class MyFastBufferPlugin final : public vlink::FastBufferPluginInterface {
72  * // Implement the allocation, access and sharing contract below.
73  * };
74  * VLINK_PLUGIN_DECLARE(MyFastBufferPlugin, 1, 0)
75  * @endcode
76  * Set @c VLINK_FASTBUFFER_PLUGIN before the process creates its first buffer.
77  * The interface ABI and the descriptor protocol ID are separate compatibility
78  * contracts; the latter identifies interoperable native descriptors within the core envelope.
79  */
80 
81 #pragma once
82 
83 #include <cstddef>
84 #include <cstdint>
85 
86 #include "../base/plugin.h"
87 #include "./fast_buffer.h"
88 
89 namespace vlink {
90 
91 /**
92  * @class FastBufferPluginInterface
93  * @brief Supplies platform buffers without exposing a vendor runtime to VLink.
94  *
95  * @details
96  * All methods may run on different host threads; implementations select the resource's device/context.
97  * zerocopy::FastBuffer::Buffer addresses are process-local and must never be dereferenced by VLink on the CPU. Handles
98  * are plugin-owned allocation or import references, not wire data. Failed create/import calls leave their
99  * output empty and release partial resources. Successful calls return one reference, released exactly once by the
100  * host. Size and descriptor length remain constant for that reference.
101  *
102  * Export is idempotent and creates no unclaimed reference. Publishing is not an import acknowledgement:
103  * a descriptor stays importable until the owner reuses or retires the allocation, after which import
104  * fails as expired and the message is dropped like a queue overflow. FastBufferManager owns local
105  * references and a shared-memory control block per exported allocation with a generation number and a
106  * reader table keyed by process identity; the native descriptor travels inside that block. No operation
107  * waits for another process, and dead readers or owners are detected by PID plus start time. Providers
108  * whose runtime keeps imported allocations alive independently of the exporter still rely on the reader
109  * table to know when an allocation may be overwritten. Descriptors identify the host, device and
110  * synchronization state as required by the backend. OS handles require real handle transfer; a numeric
111  * FD or device address is insufficient.
112  *
113  * Published contents are immutable until all readers finish. The manager synchronizes before export;
114  * descriptors identify resources and stay stable for each local reference. The manager
115  * synchronizes before final release; an allocation is reused only through zerocopy::FastBufferPool once no
116  * local holder or live importer references it, and freed only once its reader table is empty. External device
117  * work must be completed by its owner before export, host access or release unless the provider explicitly
118  * supports waiting for it. CPU cache maintenance is not a device completion fence. A crashed importer is
119  * purged on the owner's next reclaim; forced exporter termination invalidates allocations whose SDK requires
120  * its survival; imports that attach a new mapping detect the dead owner and call @c destroy_handle() for
121  * named resources the operating system would otherwise keep. Release buffers before manager shutdown.
122  *
123  * Implementations use @c VLINK_PLUGIN_DECLARE(Implementation, 1, 0). The descriptor protocol identity
124  * is separate from this interface ABI. Compatible providers may share a protocol; unrelated providers
125  * must use different nonzero IDs. No CUDA, image format or operating-system type is required here.
126  */
129 
130  protected:
132 
133  virtual ~FastBufferPluginInterface() = default;
134 
135  public:
136  /**
137  * @brief Begins CPU access and invalidates stale host cache lines when reading.
138  *
139  * @param buffer Reference to map.
140  * @param access CPU access direction.
141  *
142  * @return Host address, or nullptr when unsupported or failed.
143  */
144  [[nodiscard]] virtual uint8_t* map(const zerocopy::FastBuffer::Buffer& buffer,
145  zerocopy::FastBuffer::Access access) noexcept = 0;
146 
147  /**
148  * @brief Ends CPU access and flushes modified host cache lines when writing.
149  *
150  * @param buffer Previously mapped reference.
151  * @param access Matching CPU access direction.
152  *
153  * @return Whether the operation succeeded; unsupported operations return false.
154  */
155  [[nodiscard]] virtual bool unmap(const zerocopy::FastBuffer::Buffer& buffer,
156  zerocopy::FastBuffer::Access access) noexcept = 0;
157 
158  /**
159  * @brief Returns a borrowed native resource for integration with the provider's device APIs.
160  *
161  * @param buffer Live reference.
162  *
163  * @return Provider-defined native object, or nullptr when unavailable.
164  */
165  [[nodiscard]] virtual const void* native_handle(const zerocopy::FastBuffer::Buffer& buffer) const noexcept {
166  (void)buffer;
167  return nullptr;
168  }
169 
170  /**
171  * @brief Retains a provider-native resource without taking the caller's reference.
172  *
173  * @param handle Provider-defined native object.
174  * @param buffer Empty output reference; failure leaves it empty.
175  *
176  * @return Whether import succeeded; unsupported operations return false.
177  */
178  [[nodiscard]] virtual bool import_native(const void* handle, zerocopy::FastBuffer::Buffer& buffer) noexcept {
179  (void)handle;
180  (void)buffer;
181  return false;
182  }
183 
184  /**
185  * @brief Returns the nonzero identity of the descriptor protocol, including its ABI version.
186  *
187  * @return Stable protocol ID shared only by interoperable implementations.
188  */
189  [[nodiscard]] virtual uint64_t get_protocol_id() const noexcept = 0;
190 
191  /**
192  * @brief Allocates an uninitialised buffer in the requested memory domain.
193  *
194  * @param size Requested nonzero byte count.
195  * @param config Requested memory domain and device.
196  * @param buffer Empty output reference; success returns exactly @p size addressable bytes.
197  *
198  * @return Whether allocation succeeded.
199  */
200  [[nodiscard]] virtual bool create(size_t size, const zerocopy::FastBuffer::Config& config,
201  zerocopy::FastBuffer::Buffer& buffer) noexcept = 0;
202 
203  /**
204  * @brief Closes the SDK resource and clears it on success; the manager has completed local work.
205  *
206  * @param buffer Live reference to release; implementations report runtime failures in their logs.
207  *
208  * @return Whether the SDK reference was closed. Failure preserves the reference and its buffer.
209  */
210  [[nodiscard]] virtual bool release(zerocopy::FastBuffer::Buffer& buffer) noexcept = 0;
211 
212  /**
213  * @brief Waits until previously submitted work using this reference has completed.
214  *
215  * @param buffer Live reference whose device/context is selected by the plugin.
216  *
217  * @return Whether synchronization succeeded.
218  */
219  [[nodiscard]] virtual bool synchronize(const zerocopy::FastBuffer::Buffer& buffer) noexcept = 0;
220 
221  /**
222  * @brief Copies between equal-sized buffers and completes the copy before returning.
223  *
224  * @param source Source reference; pending writes must be observed.
225  * @param destination Independently allocated destination.
226  *
227  * @return Whether the copy succeeded; cross-device support is implementation-defined.
228  */
229  [[nodiscard]] virtual bool copy(const zerocopy::FastBuffer::Buffer& source,
230  const zerocopy::FastBuffer::Buffer& destination) noexcept = 0;
231 
232  /**
233  * @brief Reads the complete payload into an exactly sized host view.
234  *
235  * @param source Source reference; pending writes must be observed.
236  * @param destination Writable host storage; its pointer and size must not be replaced.
237  *
238  * @return Whether the synchronous read completed.
239  */
240  [[nodiscard]] virtual bool copy_to_host(const zerocopy::FastBuffer::Buffer& source, Bytes& destination) noexcept = 0;
241 
242  /**
243  * @brief Writes a complete host payload and completes the transfer before returning.
244  *
245  * @param source Host bytes, valid only for the duration of this call.
246  * @param destination Equal-sized destination reference.
247  *
248  * @return Whether the synchronous write completed.
249  */
250  [[nodiscard]] virtual bool copy_from_host(const Bytes& source,
251  const zerocopy::FastBuffer::Buffer& destination) noexcept = 0;
252 
253  /**
254  * @brief Returns the fixed descriptor byte count for a live reference.
255  *
256  * @param buffer Reference to export.
257  *
258  * @return Nonzero descriptor size, or zero when sharing is unsupported.
259  */
260  [[nodiscard]] virtual size_t get_handle_size(const zerocopy::FastBuffer::Buffer& buffer) const noexcept {
261  (void)buffer;
262  return 0;
263  }
264 
265  /**
266  * @brief Exports the native descriptor, stable for this local reference; the manager handles synchronization.
267  *
268  * @param buffer Source reference, retained by the publisher until receivers have imported it.
269  * @param descriptor Exactly sized host view; its pointer and size must not be replaced.
270  *
271  * @return Whether export succeeded.
272  */
273  [[nodiscard]] virtual bool export_handle(const zerocopy::FastBuffer::Buffer& buffer, Bytes& descriptor) noexcept {
274  (void)buffer;
275  (void)descriptor;
276  return false;
277  }
278 
279  /**
280  * @brief Validates a native descriptor and acquires one local SDK reference.
281  *
282  * @param descriptor Untrusted wire bytes; the input storage is not retained.
283  * @param buffer Empty output reference with an address valid in the importing process.
284  *
285  * @return Whether the protocol, host, device, allocation and synchronization are usable.
286  */
287  [[nodiscard]] virtual bool import_handle(const Bytes& descriptor, zerocopy::FastBuffer::Buffer& buffer) noexcept {
288  (void)descriptor;
289  (void)buffer;
290  return false;
291  }
292 
293  /**
294  * @brief Removes named operating-system resources of a descriptor whose exporting process has died.
295  *
296  * @param descriptor Native descriptor produced by @c export_handle() in the dead process.
297  *
298  * @return Whether resources were removed; providers whose runtime reclaims them on process exit return false.
299  *
300  * @note Several processes may call this for the same descriptor; tolerate resources that are already gone.
301  */
302  [[nodiscard]] virtual bool destroy_handle(const Bytes& descriptor) noexcept {
303  (void)descriptor;
304  return false;
305  }
306 
307  private:
309 };
310 
311 } // namespace vlink
Platform-independent buffer with a Header and a pointer-free wire envelope.
#define VLINK_DISALLOW_COPY_AND_ASSIGN(classname)
Deletes the copy constructor and copy-assignment operator of classname.
Definition: macros.h:174
#define VLINK_PLUGIN_REGISTER(InterfaceType)
Declares a plugin's identity from the demangled name of its abstract interface.
Definition: plugin.h:359
Holds a local memory address and an owned provider reference.
Definition: fast_buffer.h:138