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    /// Remove a pending async checkout without retaining its waiter or connection.
193    pub fn cancel_checkout(&mut self, token: u64, now: Instant) {
194        if let Some(i) = self.waiting.iter().position(|r| r.token == token) {
195            self.waiting.remove(i);
196        }
197        for i in 0..self.slots.len() {
198            if matches!(self.slots[i].state, State::Connecting(r) if r.token == token) {
199                self.close(ConnectionId {
200                    slot: i,
201                    generation: self.slots[i].generation,
202                });
203            }
204        }
205        self.schedule(now);
206    }
207    fn schedule(&mut self, now: Instant) {
208        if self.ending {
209            return;
210        }
211        while let Some(r) = self.waiting.front().copied() {
212            if r.deadline.is_some_and(|t| t <= now) {
213                self.waiting.pop_front();
214                self.events.push_back(Event::CheckoutFailed {
215                    token: r.token,
216                    error: Error::Timeout,
217                });
218                continue;
219            }
220            if let Some(id) = self.idle.pop_back() {
221                self.waiting.pop_front();
222                let s = &mut self.slots[id.slot];
223                s.state = State::Busy(r.token);
224                s.uses += 1;
225                self.events.push_back(Event::Acquired(Lease {
226                    connection: id,
227                    token: r.token,
228                }));
229                continue;
230            }
231            if self.total_count() >= self.config.max {
232                break;
233            }
234            self.waiting.pop_front();
235            let index = self
236                .slots
237                .iter()
238                .position(|s| matches!(s.state, State::Empty))
239                .unwrap_or(self.slots.len());
240            if index == self.slots.len() {
241                self.slots.push(Slot {
242                    generation: 0,
243                    state: State::Empty,
244                    born: now,
245                    uses: 0,
246                });
247            }
248            let s = &mut self.slots[index];
249            s.generation += 1;
250            s.state = State::Connecting(r);
251            s.born = now;
252            s.uses = 0;
253            self.events.push_back(Event::Connect(ConnectionId {
254                slot: index,
255                generation: s.generation,
256            }));
257        }
258    }
259    pub fn connected(&mut self, id: ConnectionId, now: Instant) -> Result<(), Error> {
260        let s = self.slot(id)?;
261        if matches!(s.state, State::Closing) {
262            return Ok(());
263        }
264        let State::Connecting(r) = s.state else {
265            return Err(Error::InvalidLease);
266        };
267        if r.deadline.is_some_and(|t| t <= now) {
268            self.events.push_back(Event::CheckoutFailed {
269                token: r.token,
270                error: Error::Timeout,
271            });
272            self.close(id);
273            return Ok(());
274        }
275        s.born = now;
276        s.state = State::Busy(r.token);
277        s.uses = 1;
278        self.events.push_back(Event::Connected(id));
279        self.events.push_back(Event::Acquired(Lease {
280            connection: id,
281            token: r.token,
282        }));
283        Ok(())
284    }
285    pub fn connect_failed(&mut self, id: ConnectionId, now: Instant) -> Result<(), Error> {
286        let s = self.slot(id)?;
287        let state = s.state;
288        if !matches!(state, State::Connecting(_) | State::Closing) {
289            return Err(Error::InvalidLease);
290        }
291        s.state = State::Empty;
292        if let State::Connecting(r) = state {
293            self.events.push_back(Event::CheckoutFailed {
294                token: r.token,
295                error: Error::ConnectionFailed,
296            });
297        }
298        self.events.push_back(Event::Removed(id));
299        self.schedule(now);
300        self.maybe_ended();
301        Ok(())
302    }
303    fn close(&mut self, id: ConnectionId) {
304        self.idle.retain(|v| *v != id);
305        self.slots[id.slot].state = State::Closing;
306        self.events.push_back(Event::Close(id));
307    }
308    pub fn checkin(&mut self, lease: Lease, now: Instant, destroy: bool) -> Result<(), Error> {
309        let s = self.slot(lease.connection)?;
310        if !matches!(s.state,State::Busy(t) if t==lease.token) {
311            return Err(Error::InvalidLease);
312        }
313        let uses = s.uses;
314        let born = s.born;
315        self.events.push_back(Event::Released(lease.connection));
316        if destroy
317            || self.ending
318            || self.config.max_uses.is_some_and(|m| uses >= m)
319            || self
320                .config
321                .max_lifetime
322                .is_some_and(|d| !d.is_zero() && now.saturating_duration_since(born) >= d)
323            || (self.waiting.is_empty() && self.idle.len() >= self.config.max_idle)
324        {
325            self.close(lease.connection);
326        } else {
327            self.slots[lease.connection.slot].state = State::Idle(now);
328            self.idle.push_back(lease.connection);
329        }
330        self.schedule(now);
331        Ok(())
332    }
333    pub fn closed(&mut self, id: ConnectionId, now: Instant) -> Result<(), Error> {
334        let s = self.slot(id)?;
335        if !matches!(s.state, State::Closing) {
336            return Err(Error::InvalidLease);
337        }
338        s.state = State::Empty;
339        self.events.push_back(Event::Removed(id));
340        self.schedule(now);
341        self.maybe_ended();
342        Ok(())
343    }
344    /// Report a broken pooled connection. Any connecting request fails once.
345    pub fn connection_error(&mut self, id: ConnectionId) -> Result<(), Error> {
346        let state = self.slot(id)?.state;
347        if matches!(state, State::Closing) {
348            return Ok(());
349        }
350        if let State::Connecting(r) = state {
351            self.events.push_back(Event::CheckoutFailed {
352                token: r.token,
353                error: Error::ConnectionFailed,
354            });
355        }
356        self.close(id);
357        Ok(())
358    }
359    pub fn next_timeout(&self) -> Option<Instant> {
360        let count = self.live_count();
361        self.waiting
362            .iter()
363            .filter_map(|r| r.deadline)
364            .chain(self.slots.iter().filter_map(|s| match s.state {
365                State::Connecting(r) => r.deadline,
366                State::Idle(since) => {
367                    let idle = if count > self.config.min {
368                        self.config
369                            .idle_timeout
370                            .filter(|d| !d.is_zero())
371                            .and_then(|d| since.checked_add(d))
372                    } else {
373                        None
374                    };
375                    let lifetime = self
376                        .config
377                        .max_lifetime
378                        .filter(|d| !d.is_zero())
379                        .and_then(|d| s.born.checked_add(d));
380                    idle.into_iter().chain(lifetime).min()
381                }
382                _ => None,
383            }))
384            .min()
385    }
386    pub fn handle_timeout(&mut self, now: Instant) {
387        let mut i = 0;
388        while i < self.waiting.len() {
389            if self.waiting[i].deadline.is_some_and(|t| t <= now) {
390                let r = self.waiting.remove(i).unwrap();
391                self.events.push_back(Event::CheckoutFailed {
392                    token: r.token,
393                    error: Error::Timeout,
394                });
395            } else {
396                i += 1;
397            }
398        }
399        for i in 0..self.slots.len() {
400            let s = &self.slots[i];
401            let id = ConnectionId {
402                slot: i,
403                generation: s.generation,
404            };
405            match s.state {
406                State::Connecting(r) if r.deadline.is_some_and(|t| t <= now) => {
407                    self.events.push_back(Event::CheckoutFailed {
408                        token: r.token,
409                        error: Error::Timeout,
410                    });
411                    self.close(id);
412                }
413                State::Idle(since)
414                    if (self.live_count() > self.config.min
415                        && self.config.idle_timeout.is_some_and(|d| {
416                            !d.is_zero() && now.saturating_duration_since(since) >= d
417                        }))
418                        || self.config.max_lifetime.is_some_and(|d| {
419                            !d.is_zero() && now.saturating_duration_since(s.born) >= d
420                        }) =>
421                {
422                    self.close(id)
423                }
424                _ => {}
425            }
426        }
427        self.schedule(now);
428    }
429    /// pg drains checked-out clients; mysql2 closes all connections on end.
430    pub fn end(&mut self) -> Result<(), Error> {
431        if self.ending {
432            return Err(Error::Closed);
433        }
434        self.ending = true;
435        while let Some(r) = self.waiting.pop_front() {
436            self.events.push_back(Event::CheckoutFailed {
437                token: r.token,
438                error: Error::Closed,
439            });
440        }
441        for i in 0..self.slots.len() {
442            let s = &self.slots[i];
443            let id = ConnectionId {
444                slot: i,
445                generation: s.generation,
446            };
447            match s.state {
448                State::Connecting(r) => {
449                    self.events.push_back(Event::CheckoutFailed {
450                        token: r.token,
451                        error: Error::Closed,
452                    });
453                    self.close(id);
454                }
455                State::Idle(_) => self.close(id),
456                State::Busy(_) if MYSQL => self.close(id),
457                _ => {}
458            }
459        }
460        self.maybe_ended();
461        Ok(())
462    }
463    fn maybe_ended(&mut self) {
464        if self.ending && !self.ended && self.total_count() == 0 {
465            self.ended = true;
466            self.events.push_back(Event::Ended);
467        }
468    }
469}
470#[cfg(test)]
471mod tests {
472    use super::*;
473    #[test]
474    fn fifo_timeouts_reuse_and_stale_release() {
475        #[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
476        let now = Instant::now();
477        #[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
478        let now = Instant::from_duration(std::time::Duration::ZERO);
479        let mut p = Pool::new(Config {
480            max: 1,
481            min: 0,
482            max_idle: 1,
483            ..Config::default()
484        })
485        .unwrap();
486        p.checkout(1, now, None).unwrap();
487        let Some(Event::Connect(id)) = p.next_event() else {
488            panic!()
489        };
490        p.connected(id, now).unwrap();
491        assert_eq!(p.next_event(), Some(Event::Connected(id)));
492        let Some(Event::Acquired(a)) = p.next_event() else {
493            panic!()
494        };
495        p.checkout(2, now, None).unwrap();
496        p.checkout(3, now, Some(now + Duration::from_secs(1)))
497            .unwrap();
498        assert_eq!(p.waiting_count(), 2);
499        p.checkin(a, now, false).unwrap();
500        assert_eq!(p.next_event(), Some(Event::Released(id)));
501        let Some(Event::Acquired(b)) = p.next_event() else {
502            panic!()
503        };
504        assert_eq!(b.token, 2);
505        assert_eq!(p.checkin(a, now, false), Err(Error::InvalidLease));
506        p.handle_timeout(now + Duration::from_secs(1));
507        assert_eq!(
508            p.next_event(),
509            Some(Event::CheckoutFailed {
510                token: 3,
511                error: Error::Timeout
512            })
513        );
514        p.checkin(b, now, false).unwrap();
515        p.next_event();
516        assert_eq!(p.idle_count(), 1);
517        let deadline = p.next_timeout().unwrap();
518        p.handle_timeout(deadline);
519        assert_eq!(p.next_event(), Some(Event::Close(id)));
520        p.closed(id, deadline).unwrap();
521        assert_eq!(p.total_count(), 0);
522        p.next_event();
523        p.end().unwrap();
524        assert_eq!(p.next_event(), Some(Event::Ended));
525        assert!(p.next_event().is_none());
526    }
527    #[test]
528    fn connect_timeout_and_late_success_do_not_acquire() {
529        #[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
530        let now = Instant::now();
531        #[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
532        let now = Instant::from_duration(std::time::Duration::ZERO);
533        let mut p = Pool::new(Config::default()).unwrap();
534        p.checkout(5, now, Some(now + Duration::from_secs(1)))
535            .unwrap();
536        let Some(Event::Connect(id)) = p.next_event() else {
537            panic!()
538        };
539        p.handle_timeout(now + Duration::from_secs(1));
540        assert_eq!(
541            p.next_event(),
542            Some(Event::CheckoutFailed {
543                token: 5,
544                error: Error::Timeout
545            })
546        );
547        assert_eq!(p.next_event(), Some(Event::Close(id)));
548        p.connected(id, now + Duration::from_secs(2)).unwrap();
549        assert!(p.next_event().is_none());
550        p.closed(id, now).unwrap();
551        assert_eq!(p.next_event(), Some(Event::Removed(id)));
552    }
553    #[test]
554    fn min_queue_limit_and_end_semantics() {
555        #[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
556        let now = Instant::now();
557        #[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
558        let now = Instant::from_duration(std::time::Duration::ZERO);
559        let mut p = Pool::new(Config {
560            max: 2,
561            min: 1,
562            queue_limit: Some(1),
563            ..Config::default()
564        })
565        .unwrap();
566        let mut leases = Vec::new();
567        for token in [1, 2] {
568            p.checkout(token, now, None).unwrap();
569            let Some(Event::Connect(id)) = p.next_event() else {
570                panic!()
571            };
572            p.connected(id, now).unwrap();
573            p.next_event();
574            let Some(Event::Acquired(lease)) = p.next_event() else {
575                panic!()
576            };
577            leases.push(lease);
578        }
579        p.checkout(3, now, None).unwrap();
580        assert_eq!(p.checkout(4, now, None), Err(Error::QueueLimit));
581        p.checkin(leases[0], now, false).unwrap();
582        p.next_event();
583        let Some(Event::Acquired(lease)) = p.next_event() else {
584            panic!()
585        };
586        assert_eq!(lease.token, 3);
587        p.checkin(lease, now, false).unwrap();
588        p.next_event();
589        p.checkin(leases[1], now, false).unwrap();
590        p.next_event();
591        let deadline = p.next_timeout().unwrap();
592        p.handle_timeout(deadline);
593        let Some(Event::Close(id)) = p.next_event() else {
594            panic!()
595        };
596        assert!(p.next_event().is_none());
597        p.closed(id, deadline).unwrap();
598        p.next_event();
599        assert_eq!(p.idle_count(), 1);
600        assert!(p.next_timeout().is_none());
601        p.checkout(5, deadline, None).unwrap();
602        let Some(Event::Acquired(lease)) = p.next_event() else {
603            panic!()
604        };
605        p.end().unwrap();
606        if !MYSQL {
607            assert!(p.next_event().is_none());
608            p.checkin(lease, deadline, false).unwrap();
609            assert_eq!(p.next_event(), Some(Event::Released(lease.connection)));
610        }
611        assert_eq!(p.next_event(), Some(Event::Close(lease.connection)));
612        p.closed(lease.connection, deadline).unwrap();
613        p.next_event();
614        assert_eq!(p.next_event(), Some(Event::Ended));
615    }
616}