VLink  2.3.0
A high-performance communication middleware
object_pool.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 object_pool.h
26  * @brief Thread-safe generic object pool with RAII handles and a tunable reset policy.
27  *
28  * @details
29  * @c ObjectPool<T> recycles previously allocated @c T instances so that hot paths avoid
30  * repeated heap traffic. Callers acquire an object through one of three entry points,
31  * use it, and then either let RAII return it automatically or hand it back manually.
32  *
33  * Acquisition variants:
34  *
35  * | Method | Returned handle | Returns to pool automatically |
36  * | -------------- | ---------------------------------- | ----------------------------------- |
37  * | @c get() | @c unique_ptr<T, PoolDeleter> | Yes, on @c unique_ptr destruction |
38  * | @c get_shared | @c shared_ptr<T> | Yes, on last @c shared_ptr release |
39  * | @c borrow() | Raw @c T* | No, caller must invoke @c give_back |
40  *
41  * Reset-policy decision table for the optional @c ResetCallback:
42  *
43  * | Policy | Reset on acquire | Reset on release | Typical use |
44  * | ------------------ | ---------------- | ---------------- | --------------------------------- |
45  * | @c kPolicyNone | No | No | Pure / stateless objects |
46  * | @c kPolicyRelease | No | Yes | Default; scrub on the return path |
47  * | @c kPolicyAcquire | Yes | No | Scrub right before use |
48  * | @c kPolicyBoth | Yes | Yes | Defence-in-depth scrubbing |
49  *
50  * Lifecycle of a pooled object:
51  *
52  * @verbatim
53  * factory ---> free list <----------+
54  * | acquire |
55  * v |
56  * in use ---> release --+ (reset on release if enabled)
57  * ^ |
58  * +--reset-on-acquire+
59  * @endverbatim
60  *
61  * @par Thread safety
62  * Every public method acquires the internal mutex so concurrent callers may
63  * interleave freely. Factory and reset callbacks run outside the mutex.
64  *
65  * @par Example
66  * @code
67  * auto pool = std::make_shared<vlink::ObjectPool<Buffer>>(
68  * []{ return std::make_unique<Buffer>(4096); },
69  * 4,
70  * 16,
71  * [](Buffer& buf){ buf.clear(); },
72  * vlink::ObjectPool<Buffer>::kPolicyRelease);
73  *
74  * {
75  * auto buf = pool->get();
76  * buf->write(payload.data(), payload.size());
77  * }
78  *
79  * Buffer* raw = pool->borrow();
80  * raw->write(payload.data(), payload.size());
81  * pool->give_back(raw);
82  * @endcode
83  */
84 
85 #pragma once
86 
87 #include <memory>
88 #include <mutex>
89 #include <utility>
90 #include <vector>
91 
92 #include "./functional.h"
93 #include "./macros.h"
94 
95 namespace vlink {
96 
97 /**
98  * @class ObjectPoolBase
99  * @brief Type-independent base of @c ObjectPool that owns counters, mutex and policy state.
100  *
101  * @details
102  * Keeps the shared bookkeeping for @c ObjectPool<T> in a single translation unit so that
103  * cold-path validation and error-throwing helpers do not need to be re-instantiated for
104  * every element type. Element storage and callbacks remain in the derived template.
105  */
107  public:
108  /**
109  * @brief Decides when (or whether) the user-supplied @c ResetCallback runs.
110  *
111  * @details
112  * Reset failures on the release path are caught and the offending object is dropped from
113  * the pool instead of being recycled. Failures on the acquire path are rethrown after
114  * the object has been put back on the free list.
115  */
116  enum Policy : uint8_t {
117  kPolicyNone = 0, ///< Never invoke the reset callback.
118  kPolicyRelease = 1, ///< Reset on the return-to-pool path.
119  kPolicyAcquire = 2, ///< Reset on the hand-out-to-caller path.
120  kPolicyBoth = 3, ///< Reset on both paths.
121  };
122 
123  /**
124  * @struct Stats
125  * @brief Point-in-time snapshot of internal pool counters.
126  */
127  struct Stats final {
128  size_t pool_size{0}; ///< Objects currently idle on the free list.
129  size_t borrowed{0}; ///< Objects currently held by callers.
130  size_t total_created{0}; ///< Cumulative objects ever produced by the factory.
131  size_t max_size{0}; ///< Configured upper bound; @c 0 means unlimited.
132  };
133 
134  /**
135  * @brief Returns the number of objects currently checked out of the pool.
136  *
137  * @return Borrowed object count.
138  */
139  [[nodiscard]] size_t borrowed() const;
140 
141  /**
142  * @brief Returns the cumulative number of objects ever produced by the factory.
143  *
144  * @return Total created count.
145  */
146  [[nodiscard]] size_t total_created() const;
147 
148  /**
149  * @brief Returns the configured upper bound on live objects.
150  *
151  * @return Maximum size; @c 0 means unlimited.
152  */
153  [[nodiscard]] size_t max_size() const noexcept;
154 
155  protected:
156  ObjectPoolBase(size_t max_size, size_t initial_size, Policy policy);
157 
158  ~ObjectPoolBase() noexcept = default;
159 
160  void safe_dec_borrowed_and_live() noexcept;
161 
162  [[nodiscard]] bool should_reset_on_acquire() const noexcept;
163 
164  [[nodiscard]] bool should_reset_on_release() const noexcept;
165 
166  [[noreturn]] static void throw_invalid_size();
167 
168  [[noreturn]] static void throw_factory_null_pre_fill();
169 
170  [[noreturn]] static void throw_factory_null();
171 
172  [[noreturn]] static void throw_not_shared_owned();
173 
174  [[noreturn]] void throw_exhausted(size_t pool_size) const;
175 
176  Policy policy_{kPolicyNone};
177  size_t max_size_{0};
178 
179  mutable std::mutex mutex_;
180 
181  size_t borrowed_{0};
182  size_t live_count_{0};
183  size_t total_created_{0};
184 };
185 
186 /**
187  * @class ObjectPool
188  * @brief Thread-safe recycling pool for instances of @p T with RAII acquisition.
189  *
190  * @details
191  * Must always live behind a @c std::shared_ptr because @c PoolDeleter holds a
192  * @c std::weak_ptr back to the owning pool. @c get() and @c get_shared() reject a pool that
193  * is not shared-owned with @c std::logic_error rather than handing out handles whose deleter
194  * can never return the object. Use @c std::make_shared<ObjectPool<T>>().
195  *
196  * @tparam T Pooled element type. Must be default-constructible unless a non-default
197  * factory callback is supplied.
198  */
199 template <typename T>
200 class ObjectPool : public ObjectPoolBase, public std::enable_shared_from_this<ObjectPool<T>> {
201  public:
202  /**
203  * @brief Signature of the factory used to grow the pool on demand.
204  *
205  * @details
206  * A non-null @c std::unique_ptr<T> must be returned; @c nullptr or thrown exceptions
207  * are propagated to the caller of @c get / @c get_shared / @c borrow.
208  */
210 
211  /**
212  * @brief Signature of the reset hook used to scrub objects on acquire and/or release.
213  *
214  * @details
215  * Exceptions thrown on the release path are swallowed and the affected object is
216  * discarded. Exceptions on the acquire path return the object to the pool and
217  * rethrow to the caller.
218  */
219  using ResetCallback = MoveFunction<void(T&)>;
220 
221  /**
222  * @struct PoolDeleter
223  * @brief Custom deleter installed on every RAII handle handed out by @c get / @c get_shared.
224  *
225  * @details
226  * Holds a non-owning @c weak_ptr to the parent pool. When the handle is destroyed,
227  * the deleter either returns the object via @c release() (when the pool is alive)
228  * or falls back to @c operator @c delete (when the pool has already been torn down).
229  */
230  struct PoolDeleter final {
231  /**
232  * @brief Returns @p ptr to the pool, or deletes it when the pool is gone.
233  *
234  * @param ptr Raw pointer to the object being released; @c nullptr is silently ignored.
235  */
236  void operator()(T* ptr) const noexcept;
237  std::weak_ptr<ObjectPool<T>> weak_pool; ///< Weak reference to the parent pool.
238  };
239 
240  /**
241  * @brief Constructs the pool and optionally pre-warms the free list.
242  *
243  * @param factory_callback Factory used to grow the pool. Default: @c std::make_unique<T>().
244  * @param initial_size Objects to allocate eagerly at construction time.
245  * @param max_size Cap on the number of live objects. @c 0 means unlimited.
246  * @param reset_callback Optional scrubbing hook driven by @p policy.
247  * @param policy When the reset hook fires. Default: @c kPolicyRelease.
248  *
249  * @throws std::invalid_argument when @p initial_size exceeds a non-zero @p max_size.
250  * @throws std::runtime_error when the factory returns @c nullptr while pre-filling.
251  *
252  * @note Always construct via @c std::make_shared<ObjectPool<T>>() so that
253  * @c PoolDeleter can resolve its @c weak_ptr.
254  */
255  explicit ObjectPool(FactoryCallback factory_callback = get_default_factory(), size_t initial_size = 0,
256  size_t max_size = 0, ResetCallback reset_callback = nullptr, Policy policy = kPolicyRelease);
257 
258  /**
259  * @brief Acquires an object wrapped in a @c unique_ptr with automatic return.
260  *
261  * @return RAII handle whose deleter releases the object back to the pool.
262  *
263  * @throws std::runtime_error when the pool is exhausted or the factory fails.
264  * @throws std::logic_error when the pool is not owned by a @c std::shared_ptr.
265  */
266  [[nodiscard]] std::unique_ptr<T, typename ObjectPool<T>::PoolDeleter> get();
267 
268  /**
269  * @brief Acquires an object wrapped in a @c shared_ptr with automatic return.
270  *
271  * @return RAII handle whose deleter releases the object back to the pool.
272  *
273  * @throws std::runtime_error when the pool is exhausted or the factory fails.
274  * @throws std::logic_error when the pool is not owned by a @c std::shared_ptr.
275  */
276  [[nodiscard]] std::shared_ptr<T> get_shared();
277 
278  /**
279  * @brief Acquires an object as a raw pointer; the caller owns the return path.
280  *
281  * @return Raw pointer that must later be returned via @c give_back().
282  *
283  * @throws std::runtime_error when the pool is exhausted or the factory fails.
284  */
285  [[nodiscard]] T* borrow();
286 
287  /**
288  * @brief Returns an object obtained from @c borrow() back to the pool.
289  *
290  * @param ptr Raw pointer previously returned by @c borrow(); @c nullptr is ignored.
291  */
292  void give_back(T* ptr);
293 
294  /**
295  * @brief Captures a thread-safe snapshot of pool statistics.
296  *
297  * @return Filled @c Stats value.
298  */
299  [[nodiscard]] Stats stats() const;
300 
301  /**
302  * @brief Returns the number of objects currently idle on the free list.
303  *
304  * @return Idle object count.
305  */
306  [[nodiscard]] size_t size() const;
307 
308  private:
309  static FactoryCallback get_default_factory();
310 
311  std::unique_ptr<T> acquire();
312 
313  void release(std::unique_ptr<T> obj) noexcept;
314 
315  FactoryCallback factory_callback_;
316  ResetCallback reset_callback_;
317  std::vector<std::unique_ptr<T>> pool_;
318 
320 };
321 
322 ////////////////////////////////////////////////////////////////
323 /// Details
324 ////////////////////////////////////////////////////////////////
325 
326 template <typename T>
327 inline ObjectPool<T>::ObjectPool(FactoryCallback factory_callback, size_t initial_size, size_t max_size,
328  ResetCallback reset_callback, Policy policy)
329  : ObjectPoolBase(max_size, initial_size, policy),
330  factory_callback_(std::move(factory_callback)),
331  reset_callback_(std::move(reset_callback)) {
332  pool_.reserve(initial_size);
333  for (size_t i = 0; i < initial_size; ++i) {
334  auto obj = factory_callback_();
335 
336  if VUNLIKELY (!obj) {
338  }
339 
340  if (should_reset_on_release() && reset_callback_) {
341  reset_callback_(*obj);
342  }
343 
344  pool_.emplace_back(std::move(obj));
345  }
346 
347  total_created_ = initial_size;
348  live_count_ = initial_size;
349 }
350 
351 template <typename T>
352 inline std::unique_ptr<T, typename ObjectPool<T>::PoolDeleter> ObjectPool<T>::get() {
353  std::weak_ptr<ObjectPool<T>> weak_self = this->weak_from_this();
354 
355  if VUNLIKELY (weak_self.expired()) {
356  throw_not_shared_owned();
357  }
358 
359  std::unique_ptr<T> obj = acquire();
360 
361  try {
362  if (should_reset_on_acquire() && reset_callback_) {
363  reset_callback_(*obj);
364  }
365  } catch (...) { // LCOV_EXCL_LINE GCOVR_EXCL_LINE
366  release(std::move(obj)); // LCOV_EXCL_LINE GCOVR_EXCL_LINE
367  throw; // LCOV_EXCL_LINE GCOVR_EXCL_LINE
368  }
369 
370  return {obj.release(), PoolDeleter{std::move(weak_self)}};
371 }
372 
373 template <typename T>
374 inline std::shared_ptr<T> ObjectPool<T>::get_shared() {
375  std::weak_ptr<ObjectPool<T>> weak_self = this->weak_from_this();
376 
377  if VUNLIKELY (weak_self.expired()) {
378  throw_not_shared_owned();
379  }
380 
381  std::unique_ptr<T> obj = acquire();
382 
383  try {
384  if (should_reset_on_acquire() && reset_callback_) {
385  reset_callback_(*obj);
386  }
387  } catch (...) { // LCOV_EXCL_LINE GCOVR_EXCL_LINE
388  release(std::move(obj)); // LCOV_EXCL_LINE GCOVR_EXCL_LINE
389  throw; // LCOV_EXCL_LINE GCOVR_EXCL_LINE
390  }
391 
392  return {obj.release(), PoolDeleter{std::move(weak_self)}};
393 }
394 
395 template <typename T>
397  std::unique_ptr<T> obj = acquire();
398 
399  try {
400  if (should_reset_on_acquire() && reset_callback_) {
401  reset_callback_(*obj);
402  }
403  } catch (...) { // LCOV_EXCL_LINE GCOVR_EXCL_LINE
404  release(std::move(obj)); // LCOV_EXCL_LINE GCOVR_EXCL_LINE
405  throw; // LCOV_EXCL_LINE GCOVR_EXCL_LINE
406  }
407 
408  return obj.release();
409 }
410 
411 template <typename T>
412 inline void ObjectPool<T>::give_back(T* ptr) {
413  if VUNLIKELY (!ptr) {
414  return;
415  }
416 
417  std::unique_ptr<T> u(ptr);
418  release(std::move(u));
419 }
420 
421 template <typename T>
423  std::lock_guard lock(mutex_);
424  return {pool_.size(), borrowed_, total_created_, max_size_};
425 }
426 
427 template <typename T>
428 inline size_t ObjectPool<T>::size() const {
429  std::lock_guard lock(mutex_);
430  return pool_.size();
431 }
432 
433 template <typename T>
435  return [] { return std::make_unique<T>(); };
436 }
437 
438 template <typename T>
439 inline std::unique_ptr<T> ObjectPool<T>::acquire() {
440  std::unique_lock lock(mutex_);
441 
442  if VLIKELY (!pool_.empty()) {
443  std::unique_ptr<T> obj = std::move(pool_.back());
444  pool_.pop_back();
445  ++borrowed_;
446  return obj;
447  } // LCOV_EXCL_LINE GCOVR_EXCL_LINE
448 
449  if VUNLIKELY (max_size_ > 0 && live_count_ >= max_size_) {
450  throw_exhausted(pool_.size());
451  }
452 
453  ++live_count_;
454  ++total_created_;
455  ++borrowed_;
456 
457  lock.unlock();
458 
459  std::unique_ptr<T> new_obj;
460  try {
461  new_obj = factory_callback_();
462 
463  if VUNLIKELY (!new_obj) {
464  throw_factory_null();
465  }
466  } catch (...) {
467  lock.lock();
468  --borrowed_;
469  --live_count_;
470  --total_created_;
471  throw;
472  }
473 
474  return new_obj;
475 }
476 
477 template <typename T>
478 inline void ObjectPool<T>::release(std::unique_ptr<T> obj) noexcept {
479  if VUNLIKELY (!obj) {
480  return; // LCOV_EXCL_LINE GCOVR_EXCL_LINE
481  }
482 
483  if (should_reset_on_release() && reset_callback_) {
484  try {
485  reset_callback_(*obj);
486  } catch (...) {
487  safe_dec_borrowed_and_live();
488  return;
489  }
490  }
491 
492  {
493  std::lock_guard lock(mutex_);
494 
495  if VLIKELY (borrowed_ > 0) {
496  --borrowed_;
497  }
498 
499  try {
500  pool_.emplace_back(std::move(obj));
501  } catch (...) { // LCOV_EXCL_LINE GCOVR_EXCL_LINE
502  if (live_count_ > 0) { // LCOV_EXCL_LINE GCOVR_EXCL_LINE
503  --live_count_; // LCOV_EXCL_LINE GCOVR_EXCL_LINE
504  }
505  }
506  }
507 }
508 
509 template <typename T>
510 inline void ObjectPool<T>::PoolDeleter::operator()(T* ptr) const noexcept {
511  if VUNLIKELY (!ptr) {
512  return; // LCOV_EXCL_LINE GCOVR_EXCL_LINE
513  }
514 
515  if (auto sp = weak_pool.lock()) {
516  std::unique_ptr<T> u(ptr);
517  sp->release(std::move(u));
518  } else {
519  delete ptr;
520  }
521 }
522 
523 } // namespace vlink
Pool-backed type-erased callables: copyable vlink::Function and move-only vlink::MoveFunction.
Cross-platform macros for visibility, branch hints, copy prevention, singletons and string helpers.
#define VUNLIKELY(...)
Short alias for VLINK_UNLIKELY.
Definition: macros.h:292
#define VLINK_EXPORT
Definition: macros.h:81
#define VLIKELY(...)
Short alias for VLINK_LIKELY.
Definition: macros.h:284
#define VLINK_DISALLOW_COPY_AND_ASSIGN(classname)
Deletes the copy constructor and copy-assignment operator of classname.
Definition: macros.h:174