Skip to main content

turnloop_postgres/
pool.rs

1//! Sans-I/O pool: the host executes Connect/Close requests, then reports their
2//! completion. Checkout events are FIFO; idle reuse is LIFO, as in pg/mysql2.
3use crate::Instant;
4use std::{collections::VecDeque, time::Duration};
5const MYSQL: bool = false;
6#[derive(Debug, Clone)]
7pub struct Config {
8    pub max: usize,
9    pub min: usize,
10    pub max_idle: usize,
11    pub idle_timeout: Option<Duration>,
12    pub wait_for_connections: bool,
13    pub queue_limit: Option<usize>,
14    pub max_uses: Option<u64>,
15    pub max_lifetime: Option<Duration>,
16}
17impl Default for Config {
18    fn default() -> Self {
19        Self {
20            max: 10,
21            min: 0,
22            max_idle: 10,
23            idle_timeout: Some(Duration::from_secs(if MYSQL { 60 } else { 10 })),
24            wait_for_connections: true,
25            queue_limit: None,
26            max_uses: None,
27            max_lifetime: None,
28        }
29    }
30}
31#[derive(Debug, Clone, Copy, PartialEq, Eq)]
32pub struct ConnectionId {
33    slot: usize,
34    generation: u64,
35}
36#[derive(Debug, Clone, Copy, PartialEq, Eq)]
37pub struct Lease {
38    pub connection: ConnectionId,
39    pub token: u64,
40}
41#[derive(Debug, Clone, Copy, PartialEq, Eq)]
42pub enum Error {
43    Closed,
44    QueueLimit,
45    NoConnections,
46    Timeout,
47    ConnectionFailed,
48    InvalidLease,
49    DuplicateToken,
50    InvalidConfig,
51}
52impl std::fmt::Display for Error {
53    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
54        f.write_str(match self {
55            Self::Closed => {
56                if MYSQL {
57                    "Pool is closed."
58                } else {
59                    "Cannot use a pool after calling end on the pool"
60                }
61            }
62            Self::QueueLimit => "Queue limit reached.",
63            Self::NoConnections => "No connections available.",
64            Self::Timeout => "timeout exceeded when trying to connect",
65            Self::ConnectionFailed => "connection attempt failed",
66            Self::InvalidLease => {
67                "Release called on client which has already been released to the pool."
68            }
69            Self::DuplicateToken => "duplicate checkout token",
70            Self::InvalidConfig => "invalid pool configuration",
71        })
72    }
73}
74impl std::error::Error for Error {}
75#[derive(Debug, Clone, Copy, PartialEq, Eq)]
76pub enum Event {
77    Connect(ConnectionId),
78    Connected(ConnectionId),
79    Acquired(Lease),
80    CheckoutFailed { token: u64, error: Error },
81    Released(ConnectionId),
82    Close(ConnectionId),
83    Removed(ConnectionId),
84    Ended,
85}
86#[derive(Debug, Clone, Copy)]
87struct Request {
88    token: u64,
89    deadline: Option<Instant>,
90}
91#[derive(Debug, Clone, Copy)]
92enum State {
93    Empty,
94    Connecting(Request),
95    Busy(u64),
96    Idle(Instant),
97    Closing,
98}
99struct Slot {
100    generation: u64,
101    state: State,
102    born: Instant,
103    uses: u64,
104}
105pub struct Pool {
106    config: Config,
107    slots: Vec<Slot>,
108    idle: VecDeque<ConnectionId>,
109    waiting: VecDeque<Request>,
110    events: VecDeque<Event>,
111    ending: bool,
112    ended: bool,
113}
114impl Pool {
115    pub fn new(config: Config) -> Result<Self, Error> {
116        if config.max == 0 || config.min > config.max || config.max_uses == Some(0) {
117            return Err(Error::InvalidConfig);
118        }
119        Ok(Self {
120            config,
121            slots: Vec::new(),
122            idle: VecDeque::new(),
123            waiting: VecDeque::new(),
124            events: VecDeque::new(),
125            ending: false,
126            ended: false,
127        })
128    }
129    pub fn next_event(&mut self) -> Option<Event> {
130        self.events.pop_front()
131    }
132    pub fn total_count(&self) -> usize {
133        self.slots
134            .iter()
135            .filter(|s| !matches!(s.state, State::Empty))
136            .count()
137    }
138    fn live_count(&self) -> usize {
139        self.slots
140            .iter()
141            .filter(|s| !matches!(s.state, State::Empty | State::Closing))
142            .count()
143    }
144    pub fn idle_count(&self) -> usize {
145        self.idle.len()
146    }
147    pub fn waiting_count(&self) -> usize {
148        self.waiting.len()
149    }
150    fn slot(&mut self, id: ConnectionId) -> Result<&mut Slot, Error> {
151        let s = self.slots.get_mut(id.slot).ok_or(Error::InvalidLease)?;
152        if s.generation != id.generation || matches!(s.state, State::Empty) {
153            return Err(Error::InvalidLease);
154        }
155        Ok(s)
156    }
157    /// Accepted checkouts yield exactly one Acquired or CheckoutFailed event.
158    pub fn checkout(
159        &mut self,
160        token: u64,
161        now: Instant,
162        deadline: Option<Instant>,
163    ) -> Result<(), Error> {
164        if self.ending {
165            return Err(Error::Closed);
166        }
167        if self.waiting.iter().any(|r| r.token == token)
168            || self.slots.iter().any(|s| match s.state {
169                State::Connecting(r) => r.token == token,
170                State::Busy(t) => t == token,
171                _ => false,
172            })
173        {
174            return Err(Error::DuplicateToken);
175        }
176        if self.idle.is_empty() && self.total_count() >= self.config.max {
177            if !self.config.wait_for_connections {
178                return Err(Error::NoConnections);
179            }
180            if self
181                .config
182                .queue_limit
183                .is_some_and(|max| max != 0 && self.waiting.len() >= max)
184            {
185                return Err(Error::QueueLimit);
186            }
187        }
188        self.waiting.push_back(Request { token, deadline });
189        self.schedule(now);
190        Ok(())
191    }
192    fn schedule(&mut self, now: Instant) {
193        if self.ending {
194            return;
195        }
196        while let Some(r) = self.waiting.front().copied() {
197            if r.deadline.is_some_and(|t| t <= now) {
198                self.waiting.pop_front();
199                self.events.push_back(Event::CheckoutFailed {
200                    token: r.token,
201                    error: Error::Timeout,
202                });
203                continue;
204            }
205            if let Some(id) = self.idle.pop_back() {
206                self.waiting.pop_front();
207                let s = &mut self.slots[id.slot];
208                s.state = State::Busy(r.token);
209                s.uses += 1;
210                self.events.push_back(Event::Acquired(Lease {
211                    connection: id,
212                    token: r.token,
213                }));
214                continue;
215            }
216            if self.total_count() >= self.config.max {
217                break;
218            }
219            self.waiting.pop_front();
220            let index = self
221                .slots
222                .iter()
223                .position(|s| matches!(s.state, State::Empty))
224                .unwrap_or(self.slots.len());
225            if index == self.slots.len() {
226                self.slots.push(Slot {
227                    generation: 0,
228                    state: State::Empty,
229                    born: now,
230                    uses: 0,
231                });
232            }
233            let s = &mut self.slots[index];
234            s.generation += 1;
235            s.state = State::Connecting(r);
236            s.born = now;
237            s.uses = 0;
238            self.events.push_back(Event::Connect(ConnectionId {
239                slot: index,
240                generation: s.generation,
241            }));
242        }
243    }
244    pub fn connected(&mut self, id: ConnectionId, now: Instant) -> Result<(), Error> {
245        let s = self.slot(id)?;
246        if matches!(s.state, State::Closing) {
247            return Ok(());
248        }
249        let State::Connecting(r) = s.state else {
250            return Err(Error::InvalidLease);
251        };
252        if r.deadline.is_some_and(|t| t <= now) {
253            self.events.push_back(Event::CheckoutFailed {
254                token: r.token,
255                error: Error::Timeout,
256            });
257            self.close(id);
258            return Ok(());
259        }
260        s.born = now;
261        s.state = State::Busy(r.token);
262        s.uses = 1;
263        self.events.push_back(Event::Connected(id));
264        self.events.push_back(Event::Acquired(Lease {
265            connection: id,
266            token: r.token,
267        }));
268        Ok(())
269    }
270    pub fn connect_failed(&mut self, id: ConnectionId, now: Instant) -> Result<(), Error> {
271        let s = self.slot(id)?;
272        let state = s.state;
273        if !matches!(state, State::Connecting(_) | State::Closing) {
274            return Err(Error::InvalidLease);
275        }
276        s.state = State::Empty;
277        if let State::Connecting(r) = state {
278            self.events.push_back(Event::CheckoutFailed {
279                token: r.token,
280                error: Error::ConnectionFailed,
281            });
282        }
283        self.events.push_back(Event::Removed(id));
284        self.schedule(now);
285        self.maybe_ended();
286        Ok(())
287    }
288    fn close(&mut self, id: ConnectionId) {
289        self.idle.retain(|v| *v != id);
290        self.slots[id.slot].state = State::Closing;
291        self.events.push_back(Event::Close(id));
292    }
293    pub fn checkin(&mut self, lease: Lease, now: Instant, destroy: bool) -> Result<(), Error> {
294        let s = self.slot(lease.connection)?;
295        if !matches!(s.state,State::Busy(t) if t==lease.token) {
296            return Err(Error::InvalidLease);
297        }
298        let uses = s.uses;
299        let born = s.born;
300        self.events.push_back(Event::Released(lease.connection));
301        if destroy
302            || self.ending
303            || self.config.max_uses.is_some_and(|m| uses >= m)
304            || self
305                .config
306                .max_lifetime
307                .is_some_and(|d| !d.is_zero() && now.saturating_duration_since(born) >= d)
308            || (self.waiting.is_empty() && self.idle.len() >= self.config.max_idle)
309        {
310            self.close(lease.connection);
311        } else {
312            self.slots[lease.connection.slot].state = State::Idle(now);
313            self.idle.push_back(lease.connection);
314        }
315        self.schedule(now);
316        Ok(())
317    }
318    pub fn closed(&mut self, id: ConnectionId, now: Instant) -> Result<(), Error> {
319        let s = self.slot(id)?;
320        if !matches!(s.state, State::Closing) {
321            return Err(Error::InvalidLease);
322        }
323        s.state = State::Empty;
324        self.events.push_back(Event::Removed(id));
325        self.schedule(now);
326        self.maybe_ended();
327        Ok(())
328    }
329    /// Report a broken pooled connection. Any connecting request fails once.
330    pub fn connection_error(&mut self, id: ConnectionId) -> Result<(), Error> {
331        let state = self.slot(id)?.state;
332        if matches!(state, State::Closing) {
333            return Ok(());
334        }
335        if let State::Connecting(r) = state {
336            self.events.push_back(Event::CheckoutFailed {
337                token: r.token,
338                error: Error::ConnectionFailed,
339            });
340        }
341        self.close(id);
342        Ok(())
343    }
344    pub fn next_timeout(&self) -> Option<Instant> {
345        let count = self.live_count();
346        self.waiting
347            .iter()
348            .filter_map(|r| r.deadline)
349            .chain(self.slots.iter().filter_map(|s| match s.state {
350                State::Connecting(r) => r.deadline,
351                State::Idle(since) => {
352                    let idle = if count > self.config.min {
353                        self.config
354                            .idle_timeout
355                            .filter(|d| !d.is_zero())
356                            .and_then(|d| since.checked_add(d))
357                    } else {
358                        None
359                    };
360                    let lifetime = self
361                        .config
362                        .max_lifetime
363                        .filter(|d| !d.is_zero())
364                        .and_then(|d| s.born.checked_add(d));
365                    idle.into_iter().chain(lifetime).min()
366                }
367                _ => None,
368            }))
369            .min()
370    }
371    pub fn handle_timeout(&mut self, now: Instant) {
372        let mut i = 0;
373        while i < self.waiting.len() {
374            if self.waiting[i].deadline.is_some_and(|t| t <= now) {
375                let r = self.waiting.remove(i).unwrap();
376                self.events.push_back(Event::CheckoutFailed {
377                    token: r.token,
378                    error: Error::Timeout,
379                });
380            } else {
381                i += 1;
382            }
383        }
384        for i in 0..self.slots.len() {
385            let s = &self.slots[i];
386            let id = ConnectionId {
387                slot: i,
388                generation: s.generation,
389            };
390            match s.state {
391                State::Connecting(r) if r.deadline.is_some_and(|t| t <= now) => {
392                    self.events.push_back(Event::CheckoutFailed {
393                        token: r.token,
394                        error: Error::Timeout,
395                    });
396                    self.close(id);
397                }
398                State::Idle(since)
399                    if (self.live_count() > self.config.min
400                        && self.config.idle_timeout.is_some_and(|d| {
401                            !d.is_zero() && now.saturating_duration_since(since) >= d
402                        }))
403                        || self.config.max_lifetime.is_some_and(|d| {
404                            !d.is_zero() && now.saturating_duration_since(s.born) >= d
405                        }) =>
406                {
407                    self.close(id)
408                }
409                _ => {}
410            }
411        }
412        self.schedule(now);
413    }
414    /// pg drains checked-out clients; mysql2 closes all connections on end.
415    pub fn end(&mut self) -> Result<(), Error> {
416        if self.ending {
417            return Err(Error::Closed);
418        }
419        self.ending = true;
420        while let Some(r) = self.waiting.pop_front() {
421            self.events.push_back(Event::CheckoutFailed {
422                token: r.token,
423                error: Error::Closed,
424            });
425        }
426        for i in 0..self.slots.len() {
427            let s = &self.slots[i];
428            let id = ConnectionId {
429                slot: i,
430                generation: s.generation,
431            };
432            match s.state {
433                State::Connecting(r) => {
434                    self.events.push_back(Event::CheckoutFailed {
435                        token: r.token,
436                        error: Error::Closed,
437                    });
438                    self.close(id);
439                }
440                State::Idle(_) => self.close(id),
441                State::Busy(_) if MYSQL => self.close(id),
442                _ => {}
443            }
444        }
445        self.maybe_ended();
446        Ok(())
447    }
448    fn maybe_ended(&mut self) {
449        if self.ending && !self.ended && self.total_count() == 0 {
450            self.ended = true;
451            self.events.push_back(Event::Ended);
452        }
453    }
454}
455#[cfg(test)]
456mod tests {
457    use super::*;
458    #[test]
459    fn fifo_timeouts_reuse_and_stale_release() {
460        #[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
461        let now = Instant::now();
462        #[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
463        let now = Instant::from_duration(std::time::Duration::ZERO);
464        let mut p = Pool::new(Config {
465            max: 1,
466            min: 0,
467            max_idle: 1,
468            ..Config::default()
469        })
470        .unwrap();
471        p.checkout(1, now, None).unwrap();
472        let Some(Event::Connect(id)) = p.next_event() else {
473            panic!()
474        };
475        p.connected(id, now).unwrap();
476        assert_eq!(p.next_event(), Some(Event::Connected(id)));
477        let Some(Event::Acquired(a)) = p.next_event() else {
478            panic!()
479        };
480        p.checkout(2, now, None).unwrap();
481        p.checkout(3, now, Some(now + Duration::from_secs(1)))
482            .unwrap();
483        assert_eq!(p.waiting_count(), 2);
484        p.checkin(a, now, false).unwrap();
485        assert_eq!(p.next_event(), Some(Event::Released(id)));
486        let Some(Event::Acquired(b)) = p.next_event() else {
487            panic!()
488        };
489        assert_eq!(b.token, 2);
490        assert_eq!(p.checkin(a, now, false), Err(Error::InvalidLease));
491        p.handle_timeout(now + Duration::from_secs(1));
492        assert_eq!(
493            p.next_event(),
494            Some(Event::CheckoutFailed {
495                token: 3,
496                error: Error::Timeout
497            })
498        );
499        p.checkin(b, now, false).unwrap();
500        p.next_event();
501        assert_eq!(p.idle_count(), 1);
502        let deadline = p.next_timeout().unwrap();
503        p.handle_timeout(deadline);
504        assert_eq!(p.next_event(), Some(Event::Close(id)));
505        p.closed(id, deadline).unwrap();
506        assert_eq!(p.total_count(), 0);
507        p.next_event();
508        p.end().unwrap();
509        assert_eq!(p.next_event(), Some(Event::Ended));
510        assert!(p.next_event().is_none());
511    }
512    #[test]
513    fn connect_timeout_and_late_success_do_not_acquire() {
514        #[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
515        let now = Instant::now();
516        #[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
517        let now = Instant::from_duration(std::time::Duration::ZERO);
518        let mut p = Pool::new(Config::default()).unwrap();
519        p.checkout(5, now, Some(now + Duration::from_secs(1)))
520            .unwrap();
521        let Some(Event::Connect(id)) = p.next_event() else {
522            panic!()
523        };
524        p.handle_timeout(now + Duration::from_secs(1));
525        assert_eq!(
526            p.next_event(),
527            Some(Event::CheckoutFailed {
528                token: 5,
529                error: Error::Timeout
530            })
531        );
532        assert_eq!(p.next_event(), Some(Event::Close(id)));
533        p.connected(id, now + Duration::from_secs(2)).unwrap();
534        assert!(p.next_event().is_none());
535        p.closed(id, now).unwrap();
536        assert_eq!(p.next_event(), Some(Event::Removed(id)));
537    }
538    #[test]
539    fn min_queue_limit_and_end_semantics() {
540        #[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
541        let now = Instant::now();
542        #[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
543        let now = Instant::from_duration(std::time::Duration::ZERO);
544        let mut p = Pool::new(Config {
545            max: 2,
546            min: 1,
547            queue_limit: Some(1),
548            ..Config::default()
549        })
550        .unwrap();
551        let mut leases = Vec::new();
552        for token in [1, 2] {
553            p.checkout(token, now, None).unwrap();
554            let Some(Event::Connect(id)) = p.next_event() else {
555                panic!()
556            };
557            p.connected(id, now).unwrap();
558            p.next_event();
559            let Some(Event::Acquired(lease)) = p.next_event() else {
560                panic!()
561            };
562            leases.push(lease);
563        }
564        p.checkout(3, now, None).unwrap();
565        assert_eq!(p.checkout(4, now, None), Err(Error::QueueLimit));
566        p.checkin(leases[0], now, false).unwrap();
567        p.next_event();
568        let Some(Event::Acquired(lease)) = p.next_event() else {
569            panic!()
570        };
571        assert_eq!(lease.token, 3);
572        p.checkin(lease, now, false).unwrap();
573        p.next_event();
574        p.checkin(leases[1], now, false).unwrap();
575        p.next_event();
576        let deadline = p.next_timeout().unwrap();
577        p.handle_timeout(deadline);
578        let Some(Event::Close(id)) = p.next_event() else {
579            panic!()
580        };
581        assert!(p.next_event().is_none());
582        p.closed(id, deadline).unwrap();
583        p.next_event();
584        assert_eq!(p.idle_count(), 1);
585        assert!(p.next_timeout().is_none());
586        p.checkout(5, deadline, None).unwrap();
587        let Some(Event::Acquired(lease)) = p.next_event() else {
588            panic!()
589        };
590        p.end().unwrap();
591        if !MYSQL {
592            assert!(p.next_event().is_none());
593            p.checkin(lease, deadline, false).unwrap();
594            assert_eq!(p.next_event(), Some(Event::Released(lease.connection)));
595        }
596        assert_eq!(p.next_event(), Some(Event::Close(lease.connection)));
597        p.closed(lease.connection, deadline).unwrap();
598        p.next_event();
599        assert_eq!(p.next_event(), Some(Event::Ended));
600    }
601}