fastpool/
common.rs

1// Copyright 2025 FastLabs Developers
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15use std::future::Future;
16use std::time::Instant;
17
18/// Statistics regarding an object returned by the pool.
19#[derive(Debug, Clone, Copy)]
20pub struct ObjectStatus {
21    created: Instant,
22    pub(crate) recycled: Option<Instant>,
23    pub(crate) recycle_count: usize,
24}
25
26impl Default for ObjectStatus {
27    fn default() -> Self {
28        Self {
29            created: Instant::now(),
30            recycled: None,
31            recycle_count: 0,
32        }
33    }
34}
35
36impl ObjectStatus {
37    /// Returns the instant when this object was created.
38    pub fn created(&self) -> Instant {
39        self.created
40    }
41
42    /// Returns the instant when this object was last used.
43    pub fn last_used(&self) -> Instant {
44        self.recycled.unwrap_or(self.created)
45    }
46
47    /// Returns the number of times the object was recycled.
48    pub fn recycle_count(&self) -> usize {
49        self.recycle_count
50    }
51}
52
53/// A trait whose instance creates new objects and recycles existing ones.
54pub trait ManageObject: Send + Sync {
55    /// The type of objects that this instance creates and recycles.
56    type Object: Send;
57
58    /// The type of errors that this instance can return.
59    type Error: Send;
60
61    /// Creates a new object.
62    fn create(&self) -> impl Future<Output = Result<Self::Object, Self::Error>> + Send;
63
64    /// Whether the object `o` is recyclable.
65    ///
66    /// Returns `Ok(())` if the object is recyclable; otherwise, returns an error.
67    fn is_recyclable(
68        &self,
69        o: &mut Self::Object,
70        status: &ObjectStatus,
71    ) -> impl Future<Output = Result<(), Self::Error>> + Send;
72
73    /// A callback invoked when an object is detached from the pool.
74    ///
75    /// If this instance does not hold any references to the object, then the default
76    /// implementation can be used which does nothing.
77    fn on_detached(&self, _o: &mut Self::Object) {}
78}
79
80/// Queue strategy when deque objects from the object pool.
81#[derive(Debug, Default, Clone, Copy)]
82pub enum QueueStrategy {
83    /// First in first out.
84    ///
85    /// This strategy behaves like a queue.
86    #[default]
87    Fifo,
88    /// Last in first out.
89    ///
90    /// This strategy behaves like a stack.
91    Lifo,
92}
93
94/// Strategy when recycling object has been cancelled.
95///
96/// This enum controls the behavior when the recycling process (specifically the
97/// [`ManageObject::is_recyclable`] check) is cancelled; for example, when the
98/// `get()` future is dropped.
99#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
100pub enum RecycleCancelledStrategy {
101    /// Detach the object from the pool.
102    ///
103    /// This is the safest option. If the recycling check is cancelled, we assume the object might
104    /// be in an unknown state or that the check was taking too long for a reason. The object will
105    /// detach from the pool.
106    #[default]
107    Detach,
108
109    /// Return the object to the pool for potential reuse.
110    ///
111    /// This assumes that interrupting the check does not invalidate the object. The object is put
112    /// back into the pool.
113    ReturnToPool,
114}
fastpool/common.rs

fastpool/
common.rs
