Skip to main content

turnloop_io/
pool.rs

1//! Shared executor scheduling for sans-I/O connection pools. Policies stay in
2//! protocol crates; this module owns sockets, waiter wakeups and absolute timers.
3use crate::{Backend, ExecutorHandle, Instant, error};
4use std::{
5    cell::RefCell,
6    future::{Future, poll_fn},
7    io,
8    ops::{Deref, DerefMut},
9    pin::Pin,
10    rc::Rc,
11    task::{Context, Poll, Waker},
12    time::Duration,
13};
14use turnloop::{Handle, JoinHandle, Sleep};
15
16pub enum Action<I, L> {
17    Connect(I),
18    Close(I),
19    Remove(I),
20    Acquired { token: u64, lease: L },
21    Failed { token: u64, error: io::Error },
22    Ended,
23}
24pub trait Policy: 'static {
25    type Id: Copy + Eq;
26    type Lease: Copy;
27    fn id(lease: Self::Lease) -> Self::Id;
28    fn checkout(&mut self, token: u64, now: Instant, deadline: Instant) -> io::Result<()>;
29    fn cancel(&mut self, token: u64, now: Instant);
30    fn connected(&mut self, id: Self::Id, now: Instant) -> io::Result<()>;
31    fn connect_failed(&mut self, id: Self::Id, now: Instant) -> io::Result<()>;
32    fn checkin(&mut self, lease: Self::Lease, now: Instant, destroy: bool) -> io::Result<()>;
33    fn closed(&mut self, id: Self::Id, now: Instant) -> io::Result<()>;
34    fn event(&mut self) -> Option<Action<Self::Id, Self::Lease>>;
35    fn next_deadline(&self) -> Option<Instant>;
36    fn expire(&mut self, now: Instant);
37    fn end(&mut self) -> io::Result<()>;
38}
39pub trait Connection: 'static {
40    fn reusable(&self) -> bool;
41    fn handle(&self) -> Option<Handle>;
42}
43pub trait Connector<B: Backend>: 'static {
44    type Connection: Connection;
45    fn connect(
46        &self,
47        executor: &ExecutorHandle<B>,
48        deadline: Instant,
49    ) -> impl Future<Output = io::Result<Self::Connection>> + 'static;
50}
51type Connecting<C> = Pin<Box<dyn Future<Output = io::Result<C>>>>;
52struct Entry<B: Backend, I, C> {
53    id: I,
54    client: Option<C>,
55    connecting: Option<Connecting<C>>,
56    handle: Option<Handle>,
57    closing: Option<turnloop::Close<B>>,
58    closed: bool,
59}
60struct Waiter<L> {
61    token: u64,
62    result: Option<io::Result<L>>,
63    waker: Option<Waker>,
64}
65struct State<B: Backend, P: Policy, C> {
66    policy: P,
67    entries: Vec<Entry<B, P::Id, C>>,
68    waiters: Vec<Waiter<P::Lease>>,
69    token: u64,
70    changed: Option<Waker>,
71    ended: bool,
72    end_wakers: Vec<Waker>,
73    failure: Option<String>,
74}
75struct Owner<B: Backend, P: Policy, C> {
76    state: Rc<RefCell<State<B, P, C>>>,
77    executor: ExecutorHandle<B>,
78    _task: JoinHandle<()>,
79}
80/// Cloneable pool. Checkout and release reuse retained slots after warm-up.
81pub struct Pool<B: Backend, P: Policy, C> {
82    owner: Rc<Owner<B, P, C>>,
83}
84impl<B: Backend, P: Policy, C> Clone for Pool<B, P, C> {
85    fn clone(&self) -> Self {
86        Self {
87            owner: self.owner.clone(),
88        }
89    }
90}
91fn wake(waker: &Option<Waker>) {
92    if let Some(w) = waker {
93        w.wake_by_ref();
94    }
95}
96impl<B: Backend + 'static, P: Policy, C: Connection> Pool<B, P, C> {
97    pub fn new<F: Connector<B, Connection = C>>(
98        executor: &ExecutorHandle<B>,
99        policy: P,
100        connector: F,
101        connect_timeout: Duration,
102        capacity: usize,
103    ) -> io::Result<Self> {
104        let state = Rc::new(RefCell::new(State {
105            policy,
106            entries: Vec::with_capacity(capacity),
107            waiters: Vec::with_capacity(capacity),
108            token: 0,
109            changed: None,
110            ended: false,
111            end_wakers: Vec::new(),
112            failure: None,
113        }));
114        let shared = state.clone();
115        let exec = executor.clone();
116        let mut timer: Option<(Instant, Sleep<B>)> = None;
117        let task = executor
118            .spawn_local(poll_fn(move |cx| {
119                let mut state = shared.borrow_mut();
120                state.changed = Some(cx.waker().clone());
121                let result = drive(
122                    &mut state,
123                    &exec,
124                    &connector,
125                    connect_timeout,
126                    &mut timer,
127                    cx,
128                );
129                if let Err(e) = result {
130                    state.failure = Some(e.to_string());
131                    for waiter in &state.waiters {
132                        wake(&waiter.waker);
133                    }
134                    for w in &state.end_wakers {
135                        w.wake_by_ref();
136                    }
137                    // Physical sockets close even if their client is currently leased.
138                    for entry in &state.entries {
139                        if let Some(h) = entry.handle {
140                            let _ = exec.driver().close(h, turnloop::Token(0));
141                        }
142                    }
143                    state.entries.clear();
144                    return Poll::Ready(());
145                }
146                if state.ended && state.entries.is_empty() {
147                    Poll::Ready(())
148                } else {
149                    Poll::Pending
150                }
151            }))
152            .map_err(error)?;
153        Ok(Self {
154            owner: Rc::new(Owner {
155                state,
156                executor: executor.clone(),
157                _task: task,
158            }),
159        })
160    }
161    pub fn total(&self) -> usize {
162        self.owner.state.borrow().entries.len()
163    }
164    /// Apply a topology-driven policy change and wake the pool's scheduler.
165    pub fn update_policy(&self, update: impl FnOnce(&mut P)) {
166        let mut state = self.owner.state.borrow_mut();
167        update(&mut state.policy);
168        wake(&state.changed);
169    }
170    pub async fn acquire(&self, at: Instant) -> io::Result<Lease<B, P, C>> {
171        let token = {
172            let mut state = self.owner.state.borrow_mut();
173            if let Some(e) = &state.failure {
174                return Err(io::Error::other(e.clone()));
175            }
176            state.token = state
177                .token
178                .checked_add(1)
179                .ok_or_else(|| io::Error::other("pool token exhausted"))?;
180            let token = state.token;
181            state
182                .policy
183                .checkout(token, self.owner.executor.now(), at)?;
184            state.waiters.push(Waiter {
185                token,
186                result: None,
187                waker: None,
188            });
189            wake(&state.changed);
190            token
191        };
192        let mut pending = Pending {
193            owner: &self.owner,
194            token,
195            done: false,
196        };
197        let result = crate::deadline(
198            &self.owner.executor,
199            at,
200            poll_fn(|cx| {
201                let mut state = self.owner.state.borrow_mut();
202                if let Some(e) = &state.failure {
203                    return Poll::Ready(Err(io::Error::other(e.clone())));
204                }
205                let Some(index) = state.waiters.iter().position(|w| w.token == token) else {
206                    return Poll::Ready(Err(io::Error::other("missing pool waiter")));
207                };
208                if let Some(result) = state.waiters[index].result.take() {
209                    state.waiters.swap_remove(index);
210                    return Poll::Ready(result.and_then(|lease| {
211                        let entry = state
212                            .entries
213                            .iter_mut()
214                            .find(|e| e.id == P::id(lease))
215                            .ok_or_else(|| io::Error::other("missing pooled connection"))?;
216                        let client = entry
217                            .client
218                            .take()
219                            .ok_or_else(|| io::Error::other("connection already leased"))?;
220                        Ok(Lease {
221                            owner: self.owner.clone(),
222                            client: Some(client),
223                            lease,
224                        })
225                    }));
226                }
227                state.waiters[index].waker = Some(cx.waker().clone());
228                Poll::Pending
229            }),
230        )
231        .await;
232        pending.done = result.is_ok();
233        result
234    }
235    pub async fn end(&self) -> io::Result<()> {
236        {
237            let mut state = self.owner.state.borrow_mut();
238            state.policy.end()?;
239            wake(&state.changed);
240        }
241        poll_fn(|cx| {
242            let mut state = self.owner.state.borrow_mut();
243            if let Some(e) = &state.failure {
244                return Poll::Ready(Err(io::Error::other(e.clone())));
245            }
246            if state.ended && state.entries.is_empty() {
247                return Poll::Ready(Ok(()));
248            }
249            if !state.end_wakers.iter().any(|w| w.will_wake(cx.waker())) {
250                state.end_wakers.push(cx.waker().clone());
251            }
252            Poll::Pending
253        })
254        .await
255    }
256}
257fn drive<B: Backend, P: Policy, C: Connection, F: Connector<B, Connection = C>>(
258    state: &mut State<B, P, C>,
259    executor: &ExecutorHandle<B>,
260    connector: &F,
261    timeout: Duration,
262    timer: &mut Option<(Instant, Sleep<B>)>,
263    cx: &mut Context<'_>,
264) -> io::Result<()> {
265    let now = executor.now();
266    state.policy.expire(now);
267    loop {
268        while let Some(action) = state.policy.event() {
269            match action {
270                Action::Connect(id) => state.entries.push(Entry {
271                    id,
272                    client: None,
273                    connecting: Some(Box::pin(connector.connect(executor, now + timeout))),
274                    handle: None,
275                    closing: None,
276                    closed: false,
277                }),
278                Action::Close(id) => {
279                    if let Some(entry) = state.entries.iter_mut().find(|e| e.id == id) {
280                        if let Some(h) = entry.handle {
281                            // Register physical-close observation before dropping the
282                            // client; its destructor may independently request close.
283                            entry.closing = Some(executor.close(h));
284                        }
285                        entry.client = None;
286                        entry.connecting = None;
287                        if entry.closing.is_none() {
288                            entry.closed = true;
289                            state.policy.closed(id, now)?;
290                        }
291                    } else {
292                        state.policy.closed(id, now)?;
293                    }
294                }
295                Action::Remove(id) => {
296                    if let Some(i) = state.entries.iter().position(|e| e.id == id) {
297                        state.entries.swap_remove(i);
298                    }
299                }
300                Action::Acquired { token, lease } => {
301                    if let Some(w) = state.waiters.iter_mut().find(|w| w.token == token) {
302                        w.result = Some(Ok(lease));
303                        wake(&w.waker);
304                    } else {
305                        state.policy.checkin(lease, now, true)?;
306                    }
307                }
308                Action::Failed { token, error } => {
309                    if let Some(w) = state.waiters.iter_mut().find(|w| w.token == token) {
310                        w.result = Some(Err(error));
311                        wake(&w.waker);
312                    }
313                }
314                Action::Ended => {
315                    state.ended = true;
316                    for w in &state.end_wakers {
317                        w.wake_by_ref();
318                    }
319                }
320            }
321        }
322        let mut progressed = false;
323        let closing = state.entries.iter().any(|entry| entry.closing.is_some());
324        for entry in &mut state.entries {
325            if let Some(future) = &mut entry.closing
326                && let Poll::Ready(result) = Pin::new(future).poll(cx)
327            {
328                result.map_err(error)?;
329                entry.closing = None;
330                entry.closed = true;
331                progressed = true;
332                state.policy.closed(entry.id, now)?;
333            }
334            if !closing
335                && let Some(future) = &mut entry.connecting
336                && let Poll::Ready(result) = future.as_mut().poll(cx)
337            {
338                entry.connecting = None;
339                progressed = true;
340                match result {
341                    Ok(client) => {
342                        entry.handle = client.handle();
343                        entry.client = Some(client);
344                        state.policy.connected(entry.id, now)?;
345                    }
346                    Err(_) => state.policy.connect_failed(entry.id, now)?,
347                }
348            }
349        }
350        state.entries.retain(|entry| !entry.closed);
351        if state.ended && state.entries.is_empty() {
352            for w in &state.end_wakers {
353                w.wake_by_ref();
354            }
355        }
356        if !progressed {
357            break;
358        }
359    }
360    let at = state.policy.next_deadline();
361    if timer.as_ref().map(|(at, _)| *at) != at {
362        *timer = at.map(|at| (at, executor.sleep_until(at)));
363    }
364    if let Some((_, sleep)) = timer
365        && let Poll::Ready(result) = Pin::new(sleep).poll(cx)
366    {
367        result.map_err(error)?;
368        *timer = None;
369        cx.waker().wake_by_ref();
370    }
371    Ok(())
372}
373struct Pending<'a, B: Backend, P: Policy, C> {
374    owner: &'a Rc<Owner<B, P, C>>,
375    token: u64,
376    done: bool,
377}
378impl<B: Backend, P: Policy, C> Drop for Pending<'_, B, P, C> {
379    fn drop(&mut self) {
380        if !self.done {
381            let mut state = self.owner.state.borrow_mut();
382            if let Some(i) = state.waiters.iter().position(|w| w.token == self.token) {
383                if let Some(Ok(lease)) = state.waiters.swap_remove(i).result {
384                    let _ = state.policy.checkin(lease, self.owner.executor.now(), true);
385                } else {
386                    state.policy.cancel(self.token, self.owner.executor.now());
387                }
388            }
389            wake(&state.changed);
390        }
391    }
392}
393/// Exclusive client ownership. A cancelled query makes reusable() false; release
394/// then destroys the connection instead of handing wire state to another caller.
395pub struct Lease<B: Backend, P: Policy, C: Connection> {
396    owner: Rc<Owner<B, P, C>>,
397    client: Option<C>,
398    lease: P::Lease,
399}
400impl<B: Backend, P: Policy, C: Connection> Deref for Lease<B, P, C> {
401    type Target = C;
402    fn deref(&self) -> &C {
403        self.client.as_ref().expect("owned lease")
404    }
405}
406impl<B: Backend, P: Policy, C: Connection> DerefMut for Lease<B, P, C> {
407    fn deref_mut(&mut self) -> &mut C {
408        self.client.as_mut().expect("owned lease")
409    }
410}
411impl<B: Backend, P: Policy, C: Connection> Drop for Lease<B, P, C> {
412    fn drop(&mut self) {
413        let mut state = self.owner.state.borrow_mut();
414        if let Some(client) = self.client.take()
415            && let Some(entry) = state.entries.iter_mut().find(|e| e.id == P::id(self.lease))
416        {
417            let destroy = !client.reusable();
418            entry.client = Some(client);
419            let _ = state
420                .policy
421                .checkin(self.lease, self.owner.executor.now(), destroy);
422        }
423        wake(&state.changed);
424    }
425}