Struct Pool 

pub struct Pool { /* private fields */ }

连接池核心实现

所有字段均为 Arc 或内部含 Arc（Notify、PoolConfig 可 clone）， 因此 Pool 可低成本 clone（仅增加引用计数）。PooledConnection 持有 Pool 的 clone 以实现 Drop 自动归还。

Implementations

impl Pool

pub fn new( config: PoolConfig, factory: Arc<dyn ConnectionFactory>, ) -> Result<Pool, PoolError>

创建连接池

L-5 修复：补充示例文档

示例

use sz_orm_core::pool::{Pool, PoolConfig, PoolConfigBuilder, ConnectionFactory};
use std::sync::Arc;

struct MyFactory;
impl ConnectionFactory for MyFactory {
    // ...
}

let config = PoolConfigBuilder::new()
    .max_size(10)
    .acquire_timeout(std::time::Duration::from_secs(30))
    .build();
let pool = Pool::new(config, Arc::new(MyFactory))?;

pub async fn prewarm(&self)

连接池预热（TASK-021）

当 PoolConfig::prewarm 为 true 时，调用此方法会立即建立 min_idle 个连接 并放入空闲队列。预热失败不阻断池创建（仅记录 tracing::warn!）。

注意：Pool::new() 是同步方法，无法内部执行异步预热。 调用方需要在创建池后手动调用 pool.prewarm().await：

let config = PoolConfig::default().with_prewarm(true).min_idle(5);
let pool = Pool::new(config, factory)?;
pool.prewarm().await; // 手动预热
// 此时池中已有 5 个连接

预热后首次 acquire() 延迟 < 10ms（对比冷启动 < 100ms）。

pub fn config(&self) -> &PoolConfig

获取配置

pub async fn acquire(&self) -> Result<PooledConnection, PoolError>

从池中获取连接（带超时）

L-5 修复：补充示例文档

超时时间由 PoolConfig::acquire_timeout 控制，默认 30 秒。 若超时则返回 PoolError::AcquireTimeout。

示例

// 从池中获取连接
let conn = pool.acquire().await?;
// 使用连接执行查询...
// conn.query("SELECT 1").await?;

pub async fn release(&self, pooled: PooledConnection)

释放连接回池中 如果池已关闭或连接已断开，则直接关闭连接而不是放回池中。

接收 PooledConnection 以保留原始 created_at，避免 max_lifetime 在每次归还后被重置（Critical bug fix）。

显式调用 release 后，pooled.pool 设为 None，避免 Drop 重复归还。

pub async fn status(&self) -> PoolStatus

获取池状态

v1.1.0 优化 2：idle 长度从 Mutex::lock().await 改为 ArrayQueue::len() （原子 load，无任何等待）。该方法保留 async 签名以兼容旧调用方。

pub fn pool_metrics(&self) -> PoolMetrics

获取连接池累计统计指标（Prometheus 风格）

返回池生命周期内的累计计数，可通过监控系统（如 Prometheus 抓取） 观察连接池的健康状况与压力：

• acquire_count / acquire_failed_count：获取成功率
• acquire_wait_time：池满时等待的累计时长（配合 average_acquire_wait_time() 评估延迟）
• connection_created_count / connection_closed_count：连接波动

计数基于无锁原子操作，调用开销可忽略。

pub async fn reap_idle(&self)

回收空闲过久的连接

pub async fn close_all(&self)

关闭所有空闲连接，并标记池为已关闭 注意：已借出未归还的连接不受影响，但归还时会被直接关闭； 同时 close_all 后的新 acquire 也会被拒绝。

pub async fn health_check(&self) -> u32

M-7 修复：连接池健康检查（heartbeat）

对所有空闲连接执行 ping()，移除已断开或 ping 失败的连接。 调用方应定期调用此方法（如每 60 秒），以清理失效连接。

返回值

返回被移除的连接数。

注意

• v1.1.0 优化 2 后：使用无锁 ArrayQueue，不再持 Mutex 锁。 仍可能在 ping 期间阻塞 acquire（因为连接已被取出），但不再阻塞 release。
• 仅检查空闲连接，不影响已借出的连接
• 对于大量空闲连接，可能产生较多并发 ping，建议在低峰期执行

pub async fn shutdown(&self)

优雅停机：关闭所有空闲连接，等待所有在途连接归还

1. 标记池为已关闭（拒绝新 acquire）
2. 通知所有等待者（让 acquire 等待者立即返回 Closed 错误）
3. 关闭所有空闲连接（立即释放，避免 wait 阶段无意义等待）
4. 等待在途（已借出）连接归还（带 30 秒超时）

pub fn resize(&self, new_max: usize)

动态调整连接池最大容量（resize 的别名，接受 usize）

简化实现：仅更新动态 max_size 值，在 acquire 时检查新值。

• 如果 new_max 大于当前值，允许创建更多连接（受 ArrayQueue 容量限制： 超出原始 max_size 的空闲连接会在 release 时因队列满而被关闭）
• 如果 new_max 小于当前值，不立即关闭多余连接，但阻止新连接创建 （多余连接会在 release/reap_idle 时自然回收）

pub fn set_max_size(&self, new_max: u32)

动态调整连接池最大容量

pub fn max_size(&self) -> u32

获取当前动态 max_size

pub async fn warmup(&self, min_idle: usize) -> Result<(), PoolError>

预热连接池：创建指定数量的连接放入空闲队列

不会超过 dynamic_max_size 上限。创建失败时停止预热并返回 Ok。

pub async fn query_with_timeout( &self, sql: &str, ) -> Result<Vec<HashMap<String, Value>>, DbError>

带超时的查询执行

强制 query_timeout 配置生效：使用 tokio::time::timeout 包裹 conn.query(sql)，超时返回 DbError::QueryError。未配置时使用 30 秒默认值。

Trait Implementations

impl Clone for Pool

Pool 克隆：仅增加 Arc 引用计数，成本极低

克隆后的 Pool 与原 Pool 共享同一组连接池状态（idle 队列、计数器等）。

fn clone(&self) -> Pool

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.