include/boost/corosio/detail/object_pool.hpp

94.2% Lines (65 / 69) 78.6% Branches (33 / 42) 98.7% Functions (150 / 152)

[ ] prev/next file n p prev/next uncovered line

object_pool.hpp

f(x) Functions (152)

Function Calls Lines Branches Blocks

Line	Branch	Hits	Source Code
1			//
2			// Copyright (c) 2025 Steve Gerbino ([email protected])
3			//
4			// Distributed under the Boost Software License, Version 1.0. (See accompanying
5			// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6			//
7			// Official repository: https://github.com/cppalliance/corosio
8			//
9
10			#ifndef BOOST_COROSIO_DETAIL_OBJECT_POOL_HPP
11			#define BOOST_COROSIO_DETAIL_OBJECT_POOL_HPP
12
13			#include <boost/corosio/detail/config.hpp>
14			#include <boost/corosio/detail/intrusive.hpp>
15			#include <boost/corosio/detail/object_ref.hpp>
16			#include <atomic>
17			#include <cstddef>
18			#include <initializer_list>
19			#include <limits>
20			#include <mutex>
21			#include <utility>
22			#include <vector>
23
24			namespace boost::corosio::detail {
25
26			/** Per-service recycling pool for I/O implementations.
27
28			Replaces per-impl `shared_ptr` ownership: a service news an impl
29			once, then `recycle()` (the impl's `retire()` action) parks
30			it on the free list and `acquire()` hands it back out, so steady-state
31			construct/destroy allocates nothing. Unbounded; memory is released
32			only on pool destruction. Debug poisoning, where an impl does it,
33			happens in that impl's `retire()`, not here (the pool cannot know
34			which bytes are resettable).
35
36			A service tears down its impls by calling `shutdown()`, which
37			enters shutting-down mode and visits every live impl in one
38			critical section; subsequent zero-ref crossings delete instead of
39			recycling.
40
41			`adopt()` and `remove()` are protected ownership-transfer
42			primitives for sanctioned extensions — a derived pool exposing
43			them to a caller that tracks some of its live impls through its
44			own structure instead of this pool's `live_` list (the timer
45			service, via its expiry heap) — rather than part of the public
46			surface every ordinary service uses.
47
48			@par Thread Safety
49			Distinct objects: Safe. Shared objects: Safe; all operations lock
50			an internal mutex.
51			*/
52			template<class Impl>
53			class object_pool
54			{
55			std::mutex mutex_;
56			intrusive_list<Impl> live_;
57			intrusive_list<Impl> free_;
58			bool shutting_down_ = false;
59
60			/** Marks `refs_` on an impl currently parked in `free_`.
61
62			`intrusive_list::remove()` cannot distinguish "linked in
63			`free_`" from "linked in `live_`" by inspecting the node
64			alone — both lists share one `next_`/`prev_` pair per impl —
65			so `recycle()` cannot safely call `live_.remove()` on an impl
66			it does not already know is live. Stamping this sentinel into
67			`refs_` the moment an impl joins `free_`, and checking it
68			before touching either list, is what lets `recycle()` and
69			`remove()` tell the two cases apart in every build mode, not
70			just under asserts. `acquire()` always overwrites it with 1
71			before the impl is usable again.
72			*/
73			static constexpr std::size_t pooled_sentinel = pooled_refs;
74
75			/// Check whether @p impl is parked in `free_` (`refs_` reads the
76			/// sentinel). Callers must check this before any list operation —
77			/// see the class-level comment on `pooled_sentinel`.
78		38756x	static bool is_pooled(Impl const* impl) noexcept
79			{
80		38756x	return impl->refs_.load(std::memory_order_relaxed) ==
81		38756x	pooled_sentinel;
82			}
83
84			protected:
85			/** Track a fresh or reset impl as live.
86
87			@pre @p impl is not parked in `free_` (`refs_` must not read
88			`pooled_sentinel`). The same list-corruption hazard
89			`recycle()`'s class-level comment documents applies here: a
90			free-listed impl pushed onto `live_` directly, bypassing
91			`acquire()`, would end up linked in both lists through one shared
92			`next_`/`prev_` pair.
93
94			@pre The caller is not racing `shutdown()`. Every caller adopts
95			while constructing an object (`acquire()`, or a derived pool's
96			cache handing a parked impl back out), and construction is
97			expected to stop before the service's own `shutdown()` runs;
98			this is checked only in debug builds because the failure mode
99			is a silently orphaned impl (no close callback), not memory
100			corruption.
101			*/
102		15682x	void adopt(Impl* impl)
103			{
104	1/1 ✓ Branch 2 → 3 taken 15682 times.	15682x	std::lock_guard lock(mutex_);
105	1/2 ✗ Branch 4 → 5 not taken. ✓ Branch 4 → 6 taken 15682 times.	15682x	if (is_pooled(impl))
106			{
107		✗	BOOST_COROSIO_ASSERT(false);
108			return;
109			}
110	1/2 ✗ Branch 6 → 7 not taken. ✓ Branch 6 → 8 taken 15682 times.	15682x	BOOST_COROSIO_ASSERT(!shutting_down_);
111		15682x	live_.push_back(impl);
112		15682x	}
113
114			/** Unlink a live impl without recycling (ownership transfer).
115
116			Used by a caller that is taking an impl out of this pool's
117			bookkeeping entirely (a thread-local cache slot, a direct
118			delete during shutdown) rather than parking it on `free_`.
119
120			@pre @p impl is not parked in `free_` (`refs_` must not read
121			`pooled_sentinel`). The same list-corruption hazard
122			`recycle()`'s class-level comment documents applies here: a
123			free-listed impl would be spliced out using `live_`'s
124			boundary pointers instead of `free_`'s.
125
126			@return True if @p impl was linked in `live_` and has now
127			been removed; false if it was already detached.
128			*/
129		5046x	bool remove(Impl* impl) noexcept
130			{
131		5046x	std::lock_guard lock(mutex_);
132	1/2 ✗ Branch 4 → 5 not taken. ✓ Branch 4 → 6 taken 5046 times.	5046x	if (is_pooled(impl))
133			{
134		✗	BOOST_COROSIO_ASSERT(false);
135			return false;
136			}
137		5046x	return live_.remove(impl);
138		5046x	}
139
140			public:
141			/** Destroy the pool, freeing every impl still parked or live.
142
143			A live impl is deleted whatever its count. Keepalives it holds
144			on itself (an embedded op's `object_ref`) are released by its
145			own destructor; the count is pinned first so none of those
146			releases reaches zero and calls `retire()` on an object that
147			is already being destroyed.
148
149			@pre `shutdown()` has already run, or no impls are live.
150			*/
151		6368x	~object_pool()
152			{
153	3/4 ✓ Branch 2 → 3 taken 10 times. ✓ Branch 2 → 6 taken 6358 times. ✗ Branch 4 → 5 not taken. ✓ Branch 4 → 6 taken 10 times.	6368x	BOOST_COROSIO_ASSERT(shutting_down_ \|\| live_.empty());
154	2/2 ✓ Branch 36 → 9 taken 12736 times. ✓ Branch 36 → 37 taken 6368 times.	19104x	for (auto* list : {&free_, &live_})
155			{
156	2/2 ✓ Branch 11 → 12 taken 7350 times. ✓ Branch 11 → 35 taken 12736 times.	20086x	while (auto* impl = list->pop_front())
157			{
158		7350x	impl->refs_.store(pooled_sentinel, std::memory_order_relaxed);
159	1/2 ✓ Branch 32 → 33 taken 7350 times. ✗ Branch 32 → 34 not taken.	7350x	delete impl;
160			}
161			}
162		6368x	}
163
164		6368x	object_pool() = default;
165			object_pool(object_pool const&) = delete;
166			object_pool& operator=(object_pool const&) = delete;
167
168			/** Pop-or-create an impl with the acquisition protocol applied.
169
170			Recycled impls are `reuse()`-reset and their reference count
171			restored from the pooled sentinel; fresh impls are constructed
172			in place from `args` on the cold path. Either way the impl is
173			adopted as live. This is the sequence every service's
174			`construct()` used to hand-roll. Making the pool itself the
175			only place that calls `new Impl` gives the whole library one
176			audit point for allocation policy.
177
178			@pre Not called concurrently with, or after, `shutdown()` on
179			this pool. Every caller reaches this through a service's
180			`construct()`, and service shutdown order guarantees no
181			`construct()` outlives that service's own `shutdown()`; the
182			window is only asserted in debug builds (see `adopt()`)
183			because the failure mode is an orphaned impl, not corruption.
184
185			@param args Constructor arguments for `Impl` (cold path only).
186
187			@return The acquired impl, `refs_ == 1`, tracked live.
188			*/
189			template<class... Args>
190		19870x	Impl* acquire(Args&&... args)
191			{
192			Impl* impl;
193			{
194	1/1 ✓ Branch 2 → 3 taken 19870 times.	19870x	std::lock_guard lock(mutex_);
195	1/2 ✗ Branch 3 → 4 not taken. ✓ Branch 3 → 5 taken 19870 times.	19870x	BOOST_COROSIO_ASSERT(!shutting_down_);
196		19870x	impl = free_.pop_front();
197	2/2 ✓ Branch 7 → 8 taken 7395 times. ✓ Branch 7 → 29 taken 12475 times.	19870x	if (impl)
198			{
199		7395x	impl->refs_.store(1, std::memory_order_relaxed);
200		7395x	live_.push_back(impl);
201			}
202		19870x	}
203			// reuse() runs unlocked: acquire()'s precondition excludes a
204			// concurrent shutdown() visiting the impl mid-reset.
205	2/2 ✓ Branch 30 → 31 taken 7395 times. ✓ Branch 30 → 33 taken 12475 times.	19870x	if (impl)
206			{
207		7395x	impl->reuse();
208		7395x	return impl;
209			}
210		12475x	impl = new Impl(std::forward<Args>(args)...);
211		12475x	adopt(impl);
212		12475x	return impl;
213			}
214
215			/** Move a zero-ref impl from live to the free list.
216
217			Called from `retire()`, possibly on a scheduler thread.
218			Deletes instead when shutting down. The impl must not be
219			touched after this returns.
220
221			Two accounting bugs are possible here, neither from this
222			pool's own bookkeeping but from a caller's refcounting (e.g.
223			a duplicate `retire()` for one zero-crossing). Both are
224			made safe in every build mode, not just under asserts, because
225			neither can be told apart from the correct case by a
226			`BOOST_COROSIO_ASSERT` alone that still runs the list
227			operations around it:
228
229			- `impl` is already parked in `free_` — the list-corruption
230			hazard the class-level `pooled_sentinel` comment documents.
231			The `is_pooled()` check runs first and returns before either
232			list is touched.
233			- `impl` is fully detached from `live_` and is not the
234			sentinel (not shutting down): `live_.remove()` correctly
235			returns false, but then the impl is reachable through
236			neither `acquire()` nor `shutdown()`'s visit while still
237			allocated — stranded. Deleted instead of left to leak.
238
239			While shutting down, an impl that is no longer in `live_` is
240			left alone rather than deleted: something else already took
241			it out of the pool's bookkeeping (a derived pool's owner, or a
242			duplicate retirement of an impl already deleted), and deleting
243			it again here could be a double free.
244			*/
245		18028x	void recycle(Impl* impl)
246			{
247		18028x	bool do_delete = false;
248			{
249	1/1 ✓ Branch 2 → 3 taken 18028 times.	18028x	std::lock_guard lock(mutex_);
250	1/2 ✗ Branch 4 → 5 not taken. ✓ Branch 4 → 6 taken 18028 times.	18028x	if (is_pooled(impl))
251			{
252		✗	BOOST_COROSIO_ASSERT(false);
253			return;
254			}
255
256		18028x	bool const was_live = live_.remove(impl);
257	2/2 ✓ Branch 7 → 8 taken 3287 times. ✓ Branch 7 → 9 taken 14741 times.	18028x	if (shutting_down_)
258			{
259		3287x	do_delete = was_live;
260			}
261	1/2 ✓ Branch 9 → 10 taken 14741 times. ✗ Branch 9 → 31 not taken.	14741x	else if (was_live)
262			{
263		14741x	impl->refs_.store(
264			pooled_sentinel, std::memory_order_relaxed);
265			// LIFO: the most recently retired impl is the
266			// cache-warmest candidate for the next acquire().
267		14741x	free_.push_front(impl);
268			}
269			else
270			{
271		✗	BOOST_COROSIO_ASSERT(false);
272			do_delete = true;
273			}
274		18028x	}
275	2/2 ✓ Branch 35 → 37 taken 3287 times. ✓ Branch 35 → 39 taken 14741 times.	18028x	if (do_delete)
276	1/2 ✓ Branch 37 → 38 taken 3287 times. ✗ Branch 37 → 39 not taken.	3287x	delete impl;
277			}
278
279			/** Enter shutdown mode and visit every live impl.
280
281			Sets shutting-down (subsequent zero-crossings delete instead
282			of recycling) and runs `f` on each live impl, all under one
283			critical section. Each visited impl is pinned with a reference
284			for the call and released after the critical section ends, so
285			`f` may hold on to it; an impl whose count already reached zero
286			is retiring and is skipped rather than revived.
287
288			@note The callback runs under the pool's non-recursive mutex;
289			it must not call recycle(), adopt(), or remove() on this pool.
290			*/
291			template<class F>
292		6358x	void shutdown(F&& f)
293			{
294		6358x	std::vector<Impl*> pinned;
295			{
296	1/1 ✓ Branch 2 → 3 taken 6358 times.	6358x	std::lock_guard lock(mutex_);
297		6358x	shutting_down_ = true;
298			// Sized before any pin, so a failure here leaves none held.
299		6358x	std::size_t n = 0;
300		9647x	live_.for_each([&](Impl*) { ++n; });
301	1/1 ✓ Branch 4 → 5 taken 6358 times.	6358x	pinned.reserve(n);
302	1/1 ✓ Branch 5 → 6 taken 6358 times.	6358x	live_.for_each(
303		9872x	[&](Impl* impl)
304			{
305	2/2 ✓ Branch 3 → 4 taken 4935 times. ✓ Branch 3 → 6 taken 1 time.	4936x	if (try_acquire(impl))
306			{
307		4935x	pinned.push_back(impl);
308		4935x	f(impl);
309			}
310			});
311		6358x	}
312	2/2 ✓ Branch 13 → 9 taken 4935 times. ✓ Branch 13 → 14 taken 6358 times.	11293x	for (auto* impl : pinned)
313		4935x	release(impl);
314		6358x	}
315			};
316
317			} // namespace boost::corosio::detail
318
319			#endif
320