open-net 0.3.5

A cross-platform async networking library for Rust with HTTP and WebSocket clients, network status monitoring, configurable retries, WebSocket reconnection and heartbeats, and managed client lifecycles. Reuse common networking infrastructure across applications to avoid repeated implementation and debugging, helping save development time and AI coding tokens.
Documentation
use super::data_callback_worker::DataCallbackWorker;
use super::data_callback_worker_lease::DataCallbackWorkerLease;
use super::try_start_user_callback_with;
use crate::common::log::log_def::LogType;
use std::future::Future;
use std::io;
use std::sync::mpsc::{SyncSender, TrySendError};
use std::sync::{Arc, Mutex};
use tokio::sync::Notify;

type Callback = Box<dyn FnOnce() + Send>;

/// One client-wide pool. Registration prepares one real worker; dispatch grows
/// it lazily up to the original limit and reuses busy workers if growth fails.
pub(in crate::module::ws_client) struct DataCallbackPool {
    threads: Arc<crate::common::retirement::ThreadRegistry>,
    state: Mutex<PoolState>,
    max_concurrency: usize,
    available: Arc<Notify>,
}

struct PoolState {
    workers: Vec<DataCallbackWorker>,
    closed: bool,
}

struct ReadyWorker {
    sender: SyncSender<Callback>,
    lease: DataCallbackWorkerLease,
}

struct Preparation {
    worker: Option<ReadyWorker>,
    growth_error: Option<io::Error>,
    retired: Option<DataCallbackWorker>,
}

impl DataCallbackPool {
    /// Construction does not start threads. All sessions share this same pool.
    #[cfg(test)]
    pub(in crate::module::ws_client) fn new(max_concurrency: usize) -> Self {
        Self::new_with_threads(
            max_concurrency,
            Arc::new(crate::common::retirement::ThreadRegistry::new()),
        )
    }

    pub(in crate::module::ws_client) fn new_with_threads(
        max_concurrency: usize,
        threads: Arc<crate::common::retirement::ThreadRegistry>,
    ) -> Self {
        Self {
            threads,
            state: Mutex::new(PoolState {
                workers: Vec::new(),
                closed: false,
            }),
            max_concurrency,
            available: Arc::new(Notify::new()),
        }
    }

    /// Complete first-worker initialization before transferring an inbox. A
    /// busy existing worker is sufficient: callback registration never waits
    /// for application code and later dispatch may wait in its bounded lane.
    pub(in crate::module::ws_client) fn ensure_ready(&self) -> io::Result<()> {
        let mut state = self.lock()?;
        if state.closed {
            return Err(io::Error::from(io::ErrorKind::BrokenPipe));
        }
        if state.workers.iter().any(DataCallbackWorker::is_alive) {
            return Ok(());
        }
        let (_, retired) = self.start_worker(&mut state)?;
        drop(state);
        drop(retired);
        Ok(())
    }

    /// The returned future occupies the existing dispatcher's in-flight slot.
    /// A failed optional pool expansion retains its job and waits for an
    /// initialized worker, so accepted callback buffers cannot be discarded by
    /// a later thread-allocation failure.
    pub(in crate::module::ws_client) fn dispatch(
        self: &Arc<Self>,
        callback: Callback,
    ) -> io::Result<impl Future<Output = io::Result<()>> + Send + 'static> {
        let pool = Arc::clone(self);
        Ok(async move {
            loop {
                let notified = pool.available.notified();
                tokio::pin!(notified);
                notified.as_mut().enable();
                let preparation = match pool.prepare_worker() {
                    Ok(preparation) => preparation,
                    Err(error) => {
                        // Dropping the tracked callback reports a structured
                        // dispatch failure to its subscription outside the lock.
                        return Err(error);
                    }
                };
                let Preparation {
                    worker,
                    growth_error,
                    retired,
                } = preparation;
                drop(retired);
                if let Some(error) = growth_error {
                    crate::log_e!(LogType::WSC; "ws.data_callback_pool.dispatch", "arg_callback_present|growth_error_kind", true, format!("{:?}", error.kind()));
                }
                if let Some(ReadyWorker { sender, lease }) = worker {
                    let submitted = try_start_user_callback_with(
                        "open-net-ws-data-callback",
                        move || {
                            let _lease = lease;
                            callback();
                        },
                        move |task| {
                            sender.try_send(task).map_err(|error| match error {
                                TrySendError::Full(_) => io::Error::from(io::ErrorKind::WouldBlock),
                                TrySendError::Disconnected(_) => {
                                    io::Error::from(io::ErrorKind::BrokenPipe)
                                }
                            })
                        },
                    );
                    submitted?.await;
                    return Ok(());
                }
                notified.await;
            }
        })
    }

    fn prepare_worker(&self) -> io::Result<Preparation> {
        let mut state = self.lock()?;
        if state.closed {
            return Err(io::Error::from(io::ErrorKind::BrokenPipe));
        }
        if let Some(worker) = state.workers.iter().find(|worker| worker.is_available()) {
            if let Some(lease) = worker.claim() {
                return Ok(Preparation {
                    worker: Some(ReadyWorker {
                        sender: worker.sender(),
                        lease,
                    }),
                    growth_error: None,
                    retired: None,
                });
            }
        }
        let alive = state
            .workers
            .iter()
            .filter(|worker| worker.is_alive())
            .count();
        if alive >= self.max_concurrency {
            return Ok(Preparation {
                worker: None,
                growth_error: None,
                retired: None,
            });
        }
        let (index, retired) = match self.start_worker(&mut state) {
            Ok(started) => started,
            Err(error) if alive > 0 => {
                return Ok(Preparation {
                    worker: None,
                    growth_error: Some(error),
                    retired: None,
                });
            }
            Err(error) => return Err(error),
        };
        let worker = state.workers.get(index).and_then(|worker| {
            worker.claim().map(|lease| ReadyWorker {
                sender: worker.sender(),
                lease,
            })
        });
        Ok(Preparation {
            worker,
            growth_error: None,
            retired,
        })
    }

    /// Return replaced workers for retirement after the pool mutex is released.
    fn start_worker(
        &self,
        state: &mut PoolState,
    ) -> io::Result<(usize, Option<DataCallbackWorker>)> {
        if self.max_concurrency == 0 {
            return Err(io::Error::from(io::ErrorKind::InvalidInput));
        }
        let vacant = state.workers.iter().position(|worker| !worker.is_alive());
        if vacant.is_none() {
            if state.workers.len() >= self.max_concurrency {
                return Err(io::Error::from(io::ErrorKind::WouldBlock));
            }
            state.workers.try_reserve(1).map_err(io::Error::other)?;
        }
        let worker = DataCallbackWorker::start(Arc::clone(&self.available), &self.threads)?;
        match vacant.and_then(|index| state.workers.get_mut(index).map(|slot| (index, slot))) {
            Some((index, slot)) => Ok((index, Some(std::mem::replace(slot, worker)))),
            None => {
                let index = state.workers.len();
                state.workers.push(worker);
                Ok((index, None))
            }
        }
    }

    fn lock(&self) -> io::Result<std::sync::MutexGuard<'_, PoolState>> {
        self.state
            .lock()
            .map_err(|_| io::Error::other("data callback pool lock poisoned"))
    }

    /// Stops new dispatch without waiting for arbitrary application callbacks.
    pub(in crate::module::ws_client) fn close(&self) {
        let workers = {
            let mut state = match self.state.lock() {
                Ok(state) => state,
                Err(poisoned) => {
                    crate::log_e!(LogType::WSC; "data_callback_pool", "error", "lock_poisoned_recovered");
                    poisoned.into_inner()
                }
            };
            state.closed = true;
            std::mem::take(&mut state.workers)
        };
        self.available.notify_waiters();
        drop(workers);
    }
}

impl Drop for DataCallbackPool {
    fn drop(&mut self) {
        self.close();
    }
}