VLink  2.3.0
A high-performance communication middleware
fast_buffer_pool.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_pool.h
26  * @brief Fixed-depth publisher pool that recycles @c FastBuffer allocations by generation.
27  *
28  * @details
29  * A publisher of shared descriptors must neither overwrite an allocation that importers still read nor
30  * wait for them. @c FastBufferPool owns @c depth allocations of one size and hands out the next one
31  * whose readers have all released it. The manager increments that allocation's generation first, so
32  * descriptors published earlier for it fail to import as expired instead of observing overwritten
33  * bytes. Dead reader processes are purged by identity, so a crashed subscriber never pins a slot.
34  *
35  * | Call | Effect |
36  * | ---------------------------- | ------------------------------------------------------------- |
37  * | @c create(size, depth) | Allocates @c depth uninitialised buffers through the provider |
38  * | @c acquire(buffer) | Clears @p buffer, then retains the next reusable slot |
39  * | @c clear() | Releases the slots; retained buffers keep theirs alive |
40  *
41  * @par Publish cycle
42  * @code
43  * vlink::zerocopy::FastBufferPool pool;
44  * vlink::zerocopy::FastBuffer frame;
45  * if (pool.create(frame_size, 4)) {
46  * while (running) {
47  * if (pool.acquire(frame)) {
48  * fill(frame); // map()/unmap() or device work
49  * pub.publish(frame); // shared descriptor when the provider supports it
50  * } // otherwise every slot is still being read: skip this frame
51  * } // dropping frame returns its slot without waiting
52  * }
53  * @endcode
54  * Choose @c depth larger than the deepest subscriber queue plus the frames a subscriber retains; slower
55  * subscribers then drop expired frames rather than stalling the publisher. One thread drives a pool.
56  */
57 
58 #pragma once
59 
60 #include <cstddef>
61 #include <vector>
62 
63 #include "./fast_buffer.h"
64 
65 namespace vlink {
66 
67 namespace zerocopy {
68 
69 /**
70  * @class FastBufferPool
71  * @brief Owns a fixed set of equally sized allocations and recycles them in round-robin order.
72  */
74  public:
75  FastBufferPool() noexcept = default;
76 
77  ~FastBufferPool() noexcept = default;
78 
79  /**
80  * @brief Allocates @p depth buffers of @p size bytes; failure leaves the pool unchanged.
81  *
82  * @param size Nonzero byte count of every slot.
83  * @param depth Nonzero slot count.
84  * @param config Memory type and provider-local device shared by every slot.
85  *
86  * @return Whether every slot was allocated.
87  */
88  [[nodiscard]] bool create(size_t size, size_t depth, const FastBuffer::Config& config = {}) noexcept;
89 
90  /**
91  * @brief Clears @p buffer and retains the next slot that no local holder or live importer references.
92  *
93  * @param buffer Output reference; empty when no slot is reusable.
94  *
95  * @return Whether a slot was acquired.
96  */
97  [[nodiscard]] bool acquire(FastBuffer& buffer) noexcept;
98 
99  /**
100  * @brief Returns the slot count.
101  *
102  * @return Zero before @c create().
103  */
104  [[nodiscard]] size_t depth() const noexcept { return slots_.size(); }
105 
106  /**
107  * @brief Returns the byte count of every slot.
108  *
109  * @return Zero before @c create().
110  */
111  [[nodiscard]] size_t size() const noexcept { return slots_.empty() ? 0 : slots_.front().size(); }
112 
113  /**
114  * @brief Releases the pool's slot references.
115  */
116  void clear() noexcept;
117 
118  private:
119  std::vector<FastBuffer> slots_;
120  size_t next_{0};
121 
123 };
124 
125 } // namespace zerocopy
126 
127 } // namespace vlink
Platform-independent buffer with a Header and a pointer-free wire envelope.
#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
Holds a local memory address and an owned provider reference.
Definition: fast_buffer.h:138