saluki_core/pooling/
mod.rs

1//! Object pooling.
2use std::{future::Future, sync::Arc};
3
4mod elastic;
5use saluki_metrics::static_metrics;
6
7pub use self::elastic::ElasticObjectPool;
8
9mod fixed;
10pub use self::fixed::FixedSizeObjectPool;
11
12mod on_demand;
13pub use self::on_demand::OnDemandObjectPool;
14
15pub mod helpers;
16
17/// An item that can be cleared.
18pub trait Clearable {
19    /// Clears the item.
20    fn clear(&mut self) {}
21}
22
23/// An item that is poolable.
24///
25/// This meta-trait is used to mark a type as being poolable, where the type itself wraps a piece of data
26/// (Self::Data), and the data itself is the actual value which gets pooled and reused.
27///
28/// While somewhat incestuous, what this unlocks is the ability to use wrapping types to hide away the complexity of
29/// ensuring that data which is given from an objext pool is eventully returned and not lost. Otherwise, trying to do
30/// something like using drop logic to send `T` back to an object pool would involve _replacing_ the value of `T` with a
31/// new value, which is not always possible, at least not without incurring additional allocations, which would negate
32/// the use of an object pool in the first place.
33pub trait Poolable {
34    /// The inner data value that is stored in the object pool.
35    type Data: Clearable + Send + 'static;
36
37    /// Creates a new `Self` from the object pool strategy and data value.
38    fn from_data(strategy: Arc<dyn ReclaimStrategy<Self> + Send + Sync>, data: Self::Data) -> Self;
39}
40
41/// Object pool reclamation strategy.
42///
43/// This trait is used to define the strategy for reclaiming items to an object pool.
44pub trait ReclaimStrategy<T>
45where
46    T: Poolable,
47{
48    /// Returns an item to the object pool.
49    fn reclaim(&self, data: T::Data);
50}
51
52/// An object pool.
53pub trait ObjectPool: Send + Sync {
54    /// The pooled value.
55    type Item: Send + Unpin;
56
57    /// Type of future returned by `acquire`.
58    type AcquireFuture: Future<Output = Self::Item> + Send;
59
60    /// Acquires an item from the object pool.
61    fn acquire(&self) -> Self::AcquireFuture;
62}
63
64static_metrics! {
65    name => PoolMetrics,
66    prefix => object_pool,
67    labels => [pool_name: String],
68    metrics => [
69        counter(created),
70        counter(acquired),
71        counter(released),
72        counter(deleted),
73        gauge(capacity),
74        gauge(in_use),
75    ],
76}
saluki_core/pooling/mod.rs

saluki_core/pooling/
mod.rs
