pool_mod/
lib.rs

1//! # pool-mod
2//!
3//! Generic object and connection pooling for Rust.
4//!
5//! `pool-mod` lends out reusable resources — database connections, HTTP clients,
6//! worker handles, or anything else expensive to construct — and reclaims each
7//! one automatically when the borrow ends. You describe the resource's lifecycle
8//! by implementing [`Manager`] (create, validate, recycle); the pool handles
9//! sizing, blocking acquisition with timeouts, validation-on-borrow, and
10//! idle/lifetime expiry.
11//!
12//! The pool is **runtime-agnostic**: it carries no async-runtime dependency.
13//! [`Pool::get`] blocks the calling thread until a resource is free. In an async
14//! context, acquire on a blocking-friendly executor thread (for example
15//! `tokio::task::spawn_blocking`); the returned [`Pooled`] guard is `Send`, so it
16//! can be held across `.await` points.
17//!
18//! ## Overview
19//!
20//! - [`Manager`] — the trait you implement to create, validate, and recycle
21//!   resources.
22//! - [`Pool`] — the thread-safe, cheaply-cloneable pool handle.
23//! - [`Builder`] — fluent configuration, reached through [`Pool::builder`].
24//! - [`PoolConfig`] — the underlying limits and lifecycle policy.
25//! - [`Pooled`] — the RAII guard that returns its resource to the pool on drop.
26//! - [`Status`] — a snapshot of pool occupancy.
27//! - [`Error`] — the error type, generic over the manager's own error.
28//!
29//! ## Example
30//!
31//! ```
32//! use pool_mod::{Manager, Pool};
33//! use std::convert::Infallible;
34//!
35//! // Describe how to make, reset, and (optionally) validate the resource.
36//! struct Widgets;
37//!
38//! impl Manager for Widgets {
39//!     type Resource = String;
40//!     type Error = Infallible;
41//!
42//!     fn create(&self) -> Result<String, Infallible> {
43//!         Ok(String::with_capacity(1024))
44//!     }
45//!
46//!     fn recycle(&self, buf: &mut String) -> Result<(), Infallible> {
47//!         buf.clear(); // reuse the allocation, discard the contents
48//!         Ok(())
49//!     }
50//! }
51//!
52//! // A pool of at most eight widgets, two kept ready at all times.
53//! let pool = Pool::builder(Widgets)
54//!     .max_size(8)
55//!     .min_idle(2)
56//!     .build()
57//!     .expect("configuration is valid");
58//!
59//! // Borrow one; it returns to the pool when `widget` is dropped.
60//! let mut widget = pool.get().expect("a widget is available");
61//! widget.push_str("hello");
62//! assert_eq!(widget.len(), 5);
63//! ```
64//!
65//! ## Feature flags
66//!
67//! - `std` *(default)* — enables the pool. The pool relies on `std` threading,
68//!   timing, and synchronization primitives. With `default-features = false` the
69//!   crate is `no_std` and exposes only [`VERSION`].
70//!
71//! ## License
72//!
73//! Dual-licensed under Apache-2.0 OR MIT.
74
75#![doc(html_root_url = "https://docs.rs/pool-mod")]
76#![cfg_attr(docsrs, feature(doc_cfg))]
77#![cfg_attr(not(feature = "std"), no_std)]
78#![deny(missing_docs)]
79#![deny(unsafe_op_in_unsafe_fn)]
80#![deny(unused_must_use)]
81#![deny(unused_results)]
82#![deny(clippy::unwrap_used)]
83#![deny(clippy::expect_used)]
84#![deny(clippy::todo)]
85#![deny(clippy::unimplemented)]
86#![deny(clippy::print_stdout)]
87#![deny(clippy::print_stderr)]
88#![deny(clippy::dbg_macro)]
89#![deny(clippy::unreachable)]
90#![deny(clippy::undocumented_unsafe_blocks)]
91#![deny(clippy::missing_safety_doc)]
92
93#[cfg(feature = "std")]
94mod config;
95#[cfg(feature = "std")]
96mod error;
97#[cfg(feature = "std")]
98mod manager;
99#[cfg(feature = "std")]
100mod object;
101#[cfg(feature = "std")]
102mod pool;
103#[cfg(feature = "std")]
104mod status;
105
106#[cfg(feature = "std")]
107pub use crate::config::PoolConfig;
108#[cfg(feature = "std")]
109pub use crate::error::Error;
110#[cfg(feature = "std")]
111pub use crate::manager::Manager;
112#[cfg(feature = "std")]
113pub use crate::object::Pooled;
114#[cfg(feature = "std")]
115pub use crate::pool::{Builder, Pool};
116#[cfg(feature = "std")]
117pub use crate::status::Status;
118
119/// Convenient re-exports: `use pool_mod::prelude::*;`.
120///
121/// Pulls in every public type needed to build and use a pool.
122#[cfg(feature = "std")]
123pub mod prelude {
124    pub use crate::config::PoolConfig;
125    pub use crate::error::Error;
126    pub use crate::manager::Manager;
127    pub use crate::object::Pooled;
128    pub use crate::pool::{Builder, Pool};
129    pub use crate::status::Status;
130}
131
132/// Crate version string, populated by Cargo at build time.
133pub const VERSION: &str = env!("CARGO_PKG_VERSION");
pool_mod/lib.rs

pool_mod/
lib.rs
