Skip to main content

turnloop_mongodb/
pool.rs

1//! connection-monitoring-and-pooling/connection-monitoring-and-pooling.md
2//! ยงยง Connection Pool, Connection Pool Clearing, Wait Queue, Connection Checkout.
3//! Host performs Connect/Close actions and reports authentication-ready connections.
4use crate::Instant;
5use crate::{Error, ErrorKind, Result};
6use std::{collections::VecDeque, time::Duration};
7#[derive(Clone, Copy, Debug, PartialEq, Eq)]
8pub struct Lease {
9    pub id: u64,
10    pub generation: u64,
11}
12#[derive(Debug)]
13pub enum PoolEvent {
14    Connect(Lease),
15    Close(Lease),
16    CheckedOut { token: u64, connection: Lease },
17    CheckoutFailed { token: u64, error: Error },
18    Cleared { generation: u64 },
19    Closed,
20}
21#[derive(Clone, Debug)]
22pub struct PoolOptions {
23    pub min_size: usize,
24    pub max_size: usize,
25    pub max_connecting: usize,
26    pub wait_timeout: Duration,
27    pub max_idle: Duration,
28}
29impl Default for PoolOptions {
30    fn default() -> Self {
31        Self {
32            min_size: 0,
33            max_size: 100,
34            max_connecting: 2,
35            wait_timeout: Duration::ZERO,
36            max_idle: Duration::ZERO,
37        }
38    }
39}
40#[derive(Clone, Copy, PartialEq, Eq)]
41enum Status {
42    Connecting,
43    Idle,
44    Out,
45}
46struct Entry {
47    lease: Lease,
48    status: Status,
49    last_used: Instant,
50}
51struct Waiter {
52    token: u64,
53    deadline: Option<Instant>,
54}
55pub struct Pool {
56    options: PoolOptions,
57    entries: Vec<Entry>,
58    waiters: VecDeque<Waiter>,
59    events: VecDeque<PoolEvent>,
60    generation: u64,
61    next_id: u64,
62    ready: bool,
63    closed: bool,
64}
65impl Pool {
66    pub fn new(options: PoolOptions) -> Result<Self> {
67        if options.max_connecting == 0
68            || (options.max_size != 0 && options.min_size > options.max_size)
69        {
70            return Err(Error::new(ErrorKind::InvalidArgument, "Invalid pool size"));
71        }
72        let reserve = if options.max_size == 0 {
73            100
74        } else {
75            options.max_size
76        };
77        Ok(Self {
78            options,
79            entries: Vec::with_capacity(reserve),
80            waiters: VecDeque::with_capacity(reserve),
81            events: VecDeque::with_capacity(reserve * 3 + 2),
82            generation: 0,
83            next_id: 0,
84            ready: false,
85            closed: false,
86        })
87    }
88    pub fn generation(&self) -> u64 {
89        self.generation
90    }
91    pub fn total(&self) -> usize {
92        self.entries.len()
93    }
94    pub fn checked_out(&self) -> usize {
95        self.entries
96            .iter()
97            .filter(|e| e.status == Status::Out)
98            .count()
99    }
100    pub fn ready(&mut self, now: Instant) {
101        if !self.closed {
102            self.ready = true;
103            self.drive(now);
104        }
105    }
106    pub fn checkout(&mut self, token: u64, now: Instant) -> Result<()> {
107        if self.waiters.iter().any(|w| w.token == token) {
108            return Err(Error::new(
109                ErrorKind::InvalidArgument,
110                "Duplicate checkout token",
111            ));
112        }
113        if self.closed || !self.ready {
114            self.events.push_back(PoolEvent::CheckoutFailed {
115                token,
116                error: Error::new(
117                    if self.closed {
118                        ErrorKind::PoolClosed
119                    } else {
120                        ErrorKind::PoolCleared
121                    },
122                    "Connection pool is not ready",
123                ),
124            });
125            return Ok(());
126        }
127        self.waiters.push_back(Waiter {
128            token,
129            deadline: if self.options.wait_timeout.is_zero() {
130                None
131            } else {
132                Some(now + self.options.wait_timeout)
133            },
134        });
135        self.drive(now);
136        Ok(())
137    }
138    pub fn connected(&mut self, lease: Lease, now: Instant) -> Result<()> {
139        let Some(e) = self
140            .entries
141            .iter_mut()
142            .find(|e| e.lease == lease && e.status == Status::Connecting)
143        else {
144            return Err(Error::protocol("Unknown connecting pool connection"));
145        };
146        e.status = Status::Idle;
147        e.last_used = now;
148        self.drive(now);
149        Ok(())
150    }
151    pub fn connect_failed(&mut self, lease: Lease, error: Error, now: Instant) -> Result<()> {
152        let at = self
153            .entries
154            .iter()
155            .position(|e| e.lease == lease && e.status == Status::Connecting)
156            .ok_or_else(|| Error::protocol("Unknown connecting pool connection"))?;
157        self.entries.swap_remove(at);
158        self.events.push_back(PoolEvent::Close(lease));
159        if let Some(w) = self.waiters.pop_front() {
160            self.events.push_back(PoolEvent::CheckoutFailed {
161                token: w.token,
162                error,
163            });
164        }
165        self.clear();
166        let _ = now;
167        Ok(())
168    }
169    pub fn checkin(&mut self, lease: Lease, now: Instant) -> Result<()> {
170        let at = self
171            .entries
172            .iter()
173            .position(|e| e.lease == lease && e.status == Status::Out)
174            .ok_or_else(|| Error::protocol("Unknown or already checked-in connection"))?;
175        if self.closed || lease.generation != self.generation {
176            self.entries.swap_remove(at);
177            self.events.push_back(PoolEvent::Close(lease));
178        } else {
179            self.entries[at].status = Status::Idle;
180            self.entries[at].last_used = now;
181        }
182        self.drive(now);
183        Ok(())
184    }
185    /// Discard one checked-out transport after local cancellation or corruption.
186    /// Unlike a topology clear, this preserves other leases and the pool generation.
187    pub fn discard(&mut self, lease: Lease, now: Instant) -> Result<()> {
188        let at = self
189            .entries
190            .iter()
191            .position(|e| e.lease == lease && e.status == Status::Out)
192            .ok_or_else(|| Error::protocol("Unknown checked-out connection"))?;
193        self.entries.swap_remove(at);
194        self.events.push_back(PoolEvent::Close(lease));
195        self.drive(now);
196        Ok(())
197    }
198    pub fn clear(&mut self) {
199        if self.closed {
200            return;
201        }
202        self.generation += 1;
203        self.ready = false;
204        self.events.push_back(PoolEvent::Cleared {
205            generation: self.generation,
206        });
207        let mut i = 0;
208        while i < self.entries.len() {
209            if self.entries[i].status != Status::Out {
210                let e = self.entries.swap_remove(i);
211                self.events.push_back(PoolEvent::Close(e.lease));
212            } else {
213                i += 1;
214            }
215        }
216        while let Some(w) = self.waiters.pop_front() {
217            self.events.push_back(PoolEvent::CheckoutFailed {
218                token: w.token,
219                error: Error::new(ErrorKind::PoolCleared, "Connection pool was cleared"),
220            });
221        }
222    }
223    pub fn close(&mut self) {
224        if self.closed {
225            return;
226        }
227        while let Some(w) = self.waiters.pop_front() {
228            self.events.push_back(PoolEvent::CheckoutFailed {
229                token: w.token,
230                error: Error::new(ErrorKind::PoolClosed, "Connection pool is closed"),
231            });
232        }
233        self.clear();
234        self.closed = true;
235        self.events.push_back(PoolEvent::Closed);
236    }
237    pub fn cancel_checkout(&mut self, token: u64) -> bool {
238        if let Some(i) = self.waiters.iter().position(|w| w.token == token) {
239            self.waiters.remove(i);
240            self.events.push_back(PoolEvent::CheckoutFailed {
241                token,
242                error: Error::new(ErrorKind::Cancelled, "Connection checkout cancelled"),
243            });
244            true
245        } else {
246            false
247        }
248    }
249    pub fn next_timeout(&self) -> Option<Instant> {
250        self.waiters
251            .iter()
252            .filter_map(|w| w.deadline)
253            .chain(
254                self.entries
255                    .iter()
256                    .filter(|e| e.status == Status::Idle && !self.options.max_idle.is_zero())
257                    .map(|e| e.last_used + self.options.max_idle),
258            )
259            .min()
260    }
261    pub fn handle_timeout(&mut self, now: Instant) {
262        let mut i = 0;
263        while i < self.waiters.len() {
264            if self.waiters[i].deadline.is_some_and(|d| d <= now) {
265                let w = self.waiters.remove(i).unwrap();
266                self.events.push_back(PoolEvent::CheckoutFailed {
267                    token: w.token,
268                    error: Error::new(
269                        ErrorKind::WaitQueueTimeout,
270                        "Timed out while checking out a connection from connection pool",
271                    ),
272                });
273            } else {
274                i += 1;
275            }
276        }
277        self.drive(now);
278    }
279    pub fn poll_event(&mut self) -> Option<PoolEvent> {
280        self.events.pop_front()
281    }
282    fn drive(&mut self, now: Instant) {
283        if !self.ready || self.closed {
284            return;
285        }
286        let mut i = 0;
287        while i < self.entries.len() {
288            let e = &self.entries[i];
289            if e.status == Status::Idle
290                && !self.options.max_idle.is_zero()
291                && now >= e.last_used + self.options.max_idle
292            {
293                let e = self.entries.swap_remove(i);
294                self.events.push_back(PoolEvent::Close(e.lease));
295            } else {
296                i += 1;
297            }
298        }
299        while !self.waiters.is_empty() {
300            let Some(at) = self.entries.iter().rposition(|e| e.status == Status::Idle) else {
301                break;
302            };
303            let w = self.waiters.pop_front().unwrap();
304            let e = &mut self.entries[at];
305            e.status = Status::Out;
306            self.events.push_back(PoolEvent::CheckedOut {
307                token: w.token,
308                connection: e.lease,
309            });
310        }
311        let mut connecting = self
312            .entries
313            .iter()
314            .filter(|e| e.status == Status::Connecting)
315            .count();
316        while (self.entries.len() < self.options.min_size || connecting < self.waiters.len())
317            && connecting < self.options.max_connecting
318            && (self.options.max_size == 0 || self.entries.len() < self.options.max_size)
319        {
320            self.next_id += 1;
321            let lease = Lease {
322                id: self.next_id,
323                generation: self.generation,
324            };
325            self.entries.push(Entry {
326                lease,
327                status: Status::Connecting,
328                last_used: now,
329            });
330            self.events.push_back(PoolEvent::Connect(lease));
331            connecting += 1;
332        }
333    }
334}
335
336impl From<&crate::uri::Options> for PoolOptions {
337    fn from(options: &crate::uri::Options) -> Self {
338        Self {
339            min_size: options.min_pool_size,
340            max_size: options.max_pool_size,
341            max_connecting: options.max_connecting,
342            wait_timeout: options.wait_queue_timeout,
343            max_idle: options.max_idle_time,
344        }
345    }
346}