VLink  2.3.0
A high-performance communication middleware
fast_buffer_manager.h
浏览该文件的文档.
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_manager.h
26  * @brief Process-wide provider loader and shared-resource lifetime manager.
27  *
28  * @details
29  * @c FastBufferManager owns the provider shared by every @c zerocopy::FastBuffer
30  * in the process. Construction of the first buffer resolves the provider through
31  * this singleton; nodes and CLI tools use the same selection without vendor SDK
32  * dependencies in VLink. The manager owns local references and one cross-process control block
33  * per exported allocation; buffers without sharing descriptors allocate no IPC state.
34  *
35  * | First-use environment | Provider | Manager state |
36  * | ------------------------------ | ---------------------------- | ------------- |
37  * | Unset or empty | Built-in ordinary CPU memory | Valid |
38  * | @c shm | Built-in shared CPU memory | Valid |
39  * | Compatible plugin name or path | Loaded plugin | Valid |
40  * | Missing or incompatible plugin | None | Invalid |
41  *
42  * @par Manager state machine
43  * @code
44  * first get()
45  * |
46  * v
47  * read VLINK_FASTBUFFER_PLUGIN
48  * / \
49  * unset/empty/shm name/path
50  * | |
51  * v v
52  * CPU implementation Plugin::load()
53  * | / \
54  * | valid failed
55  * v v v
56  * shared provider invalid
57  * |
58  * v
59  * FastBuffer --> core Resource
60  * |
61  * local / remote references
62  * |
63  * SDK Buffer
64  * |
65  * v
66  * release references before unloading
67  * @endcode
68  *
69  * @par Sharing control block
70  * Each exported allocation owns one named shared-memory segment; the wire descriptor names it and
71  * carries the allocation's current generation.
72  * @code
73  * Control block (shared memory) Wire descriptor (40 bytes)
74  * +-------------------------------+ +-----------------+
75  * | protocol / size / desc size | | name[32] |
76  * | owner identity | | generation |
77  * | generation (atomic) | +-----------------+
78  * | readers[32] (atomic) |
79  * +-------------------------------+
80  * | provider native descriptor |
81  * +-------------------------------+
82  * @endcode
83  * A process identity is its PID combined with the kernel start time, so a reused PID never
84  * impersonates a dead process. On Linux the block also records the owner's PID and time namespaces,
85  * because start times are reported relative to the reader's time namespace: a process in another
86  * namespace cannot judge liveness, so its imports fail and its sweeps skip the allocation.
87  * Each importing process claims one @c readers slot per allocation;
88  * further imports in that process share the local resource and only raise its local reference count.
89  * An import that attaches a new mapping fails when the reader table is full or the owner process is
90  * dead; the importer then removes the dead owner's control segment and asks the provider to destroy the
91  * native resource it names. Re-imports served by a local resource only raise its reference count. On
92  * Linux and QNX, manager construction also sweeps control segments of the same protocol left behind by
93  * dead owners; other protocols are left for a process of their own provider.
94  *
95  * @par Generation handshake
96  * Reclaiming an allocation for reuse (@c zerocopy::FastBufferPool) or retiring it increments
97  * @c generation before the owner inspects @c readers; an importer claims its slot before comparing
98  * @c generation with the descriptor. Both sides use sequentially consistent operations so that at
99  * least one observes the other: the owner sees the claim and reports the allocation busy, or the
100  * importer sees the newer generation and fails as expired. In-process importers instead compare
101  * the generation and raise the local reference count under the registry mutex, which the owner also
102  * holds while checking that count. An importer that re-exports uses the generation it imported under,
103  * so a retired allocation never becomes importable again. Reclaiming also synchronizes the provider so
104  * local device work of released readers completes before the slot is handed out. An expired import
105  * drops the message exactly like a queue overflow, so a publisher never needs an import acknowledgement.
106  *
107  * @par Lifetime without waiting
108  * Final owner release retires the allocation: the generation is incremented, dead readers are purged
109  * by identity, and the provider resource is freed immediately when no live reader remains. Otherwise
110  * the allocation joins a retired list that later create or release calls reclaim; no call ever
111  * waits for another process. Retired allocations still imported by live processes at manager shutdown
112  * are logged and released anyway, which is what process exit would do moments later; importers keep the
113  * mappings they already hold where the platform allows it.
114  *
115  * @par Locks
116  * The registry mutex protects lookup, ownership changes and the retired list. Native import and
117  * close of one name, and the first export of one allocation, are serialized by lock stripes outside
118  * the registry mutex. Non-final local release is a lock-free reference decrement.
119  *
120  * Resolution happens once. Changing the environment after the first @c get()
121  * has no effect; an explicit load failure does not select another provider.
122  * The manager owns the provider; returned pointers are borrowed. Release buffers
123  * before manager shutdown, as with the recording plugin manager.
124  *
125  * @par Example
126  * @code
127  * auto& manager = vlink::FastBufferManager::get();
128  * if (manager.is_valid()) {
129  * auto* provider = manager.get_interface();
130  * VLOG_I("FastBuffer protocol: ", provider->get_protocol_id());
131  * }
132  * @endcode
133  */
134 
135 #pragma once
136 
137 #include <memory>
138 
140 
141 namespace vlink {
142 
143 namespace zerocopy {
144 
145 class FastBufferPool;
146 
147 } // namespace zerocopy
148 
149 /**
150  * @class FastBufferManager
151  * @brief Loads one @c FastBufferPluginInterface on first use.
152  *
153  * @details
154  * Reads @c VLINK_FASTBUFFER_PLUGIN once. Empty or missing values select ordinary CPU memory and
155  * @c shm selects shared CPU memory. Explicit plugin load failures do not select CPU storage or retry.
156  * Names and paths follow @c Plugin.
157  */
159  public:
160  /**
161  * @brief Returns the lazily constructed process-wide manager.
162  *
163  * @return Singleton reference.
164  */
165  [[nodiscard]] static FastBufferManager& get();
166 
167  /**
168  * @brief Reports whether the built-in or loaded provider is available.
169  *
170  * @return Whether @c get_interface() returns a non-null pointer.
171  */
172  [[nodiscard]] bool is_valid() const;
173 
174  /**
175  * @brief Returns the provider owned by this manager.
176  *
177  * @return Borrowed provider pointer, or nullptr when unavailable.
178  */
179  [[nodiscard]] FastBufferPluginInterface* get_interface() const;
180 
181  private:
182  friend struct zerocopy::FastBuffer;
184 
185  [[nodiscard]] bool create(size_t size, const zerocopy::FastBuffer::Config& config,
186  zerocopy::FastBuffer::Buffer& buffer) noexcept;
187 
188  static void retain(const zerocopy::FastBuffer::Buffer& source, zerocopy::FastBuffer::Buffer& buffer) noexcept;
189 
190  void release(zerocopy::FastBuffer::Buffer& buffer) noexcept;
191 
192  [[nodiscard]] bool reclaim(const zerocopy::FastBuffer::Buffer& buffer) noexcept;
193 
194  [[nodiscard]] bool import_native(const void* handle, zerocopy::FastBuffer::Buffer& buffer) noexcept;
195 
196  [[nodiscard]] size_t get_handle_size(const zerocopy::FastBuffer::Buffer& buffer) const noexcept;
197 
198  [[nodiscard]] bool export_handle(const zerocopy::FastBuffer::Buffer& buffer, Bytes& descriptor) noexcept;
199 
200  [[nodiscard]] bool import_handle(const Bytes& descriptor, zerocopy::FastBuffer::Buffer& buffer) noexcept;
201 
202  [[nodiscard]] static const zerocopy::FastBuffer::Buffer& native_buffer(
203  const zerocopy::FastBuffer::Buffer& buffer) noexcept;
204 
206 
208 
209  struct Impl;
210  std::unique_ptr<Impl> impl_;
211 
213 };
214 
215 } // namespace vlink
Vendor-independent allocation and sharing contract for zerocopy::FastBuffer.
#define VLINK_EXPORT
Definition: macros.h:81
#define VLINK_DISALLOW_COPY_AND_ASSIGN(classname)
Deletes the copy constructor and copy-assignment operator of classname.
Definition: macros.h:174