pub struct PoolConfig {
pub name: String,
pub size: usize,
pub min_size: Option<usize>,
pub max_size: Option<usize>,
pub idle_timeout: Option<Duration>,
pub dispatch: DispatchStrategy,
pub health_check_interval: Option<Duration>,
pub acquisition_timeout: Option<Duration>,
pub metrics_recorder: Option<Arc<dyn MetricsRecorder>>,
}Expand description
Configuration for a connection pool.
Fields§
§name: StringStable name used to identify this pool in metrics.
Applications with multiple pools should give each one a distinct name
so their utilization and acquisition metrics remain distinguishable.
Defaults to "redis-tower".
size: usizeLegacy fixed size and fallback for omitted dynamic bounds.
With neither min_size nor max_size, the pool remains fixed at this
size. Prefer Self::bounds when opting into dynamic sizing.
min_size: Option<usize>Optional minimum number of live connections.
When omitted, Self::size is used. Idle reaping never shrinks below
this value. Set this below max_size to opt into dynamic sizing.
max_size: Option<usize>Optional maximum number of live connections.
When omitted, Self::size is used. A factory-backed pool creates new
connections up to this bound when every live slot is contended.
idle_timeout: Option<Duration>How long a completely idle connection may remain before an explicitly spawned idle reaper removes it.
Setting this value does not spawn a task. Call
ConnectionPool::spawn_idle_reaper and retain its owned handle.
dispatch: DispatchStrategyHow to select which connection handles each command.
health_check_interval: Option<Duration>If set, connections idle longer than this duration are PINGed before use.
This provides lazy health checking: when a connection has been idle beyond this interval, a PING is sent before dispatching the actual command. If the PING fails and the pool has a factory, the dead slot is replaced before the command is retried. If no factory is present, the error is returned to the caller.
acquisition_timeout: Option<Duration>Maximum time to wait for a connection slot to become available.
When all connections in the pool are busy, new callers block waiting
for a slot to free up. If the wait exceeds this duration,
RedisError::PoolAcquisitionTimeout is returned, so pool exhaustion
fails fast as a timeout instead of stalling the caller indefinitely.
Defaults to PoolConfig::DEFAULT_ACQUISITION_TIMEOUT (5 seconds).
Set it to None – via PoolConfig::disable_acquisition_timeout –
to wait forever, restoring the previous unbounded behavior.
Duration::ZERO is distinct from None: it permits an immediately
available slot but never waits for a busy one.
A command wrapped in redis_tower_core::WithDeadline can impose an
earlier limit; the earliest deadline wins.
metrics_recorder: Option<Arc<dyn MetricsRecorder>>Optional recorder for pool lifecycle metrics.
When set, the pool reports connection acquisition latency and timeouts, lazy health-check failures, and successful connection replacements.
Implementations§
Source§impl PoolConfig
impl PoolConfig
Sourcepub const DEFAULT_ACQUISITION_TIMEOUT: Duration
pub const DEFAULT_ACQUISITION_TIMEOUT: Duration
Default upper bound on how long a caller waits for a connection slot.
Used by PoolConfig::default. Five seconds is long enough to ride
out brief contention but short enough that genuine pool exhaustion
surfaces as a RedisError::PoolAcquisitionTimeout rather than an
unbounded stall that masquerades as a hang.
Sourcepub fn name(self, name: impl Into<String>) -> Self
pub fn name(self, name: impl Into<String>) -> Self
Set the stable name used to identify this pool in metrics.
Sourcepub fn min_size(self, min_size: usize) -> Self
pub fn min_size(self, min_size: usize) -> Self
Set the minimum number of live connections maintained by the pool.
Sourcepub fn max_size(self, max_size: usize) -> Self
pub fn max_size(self, max_size: usize) -> Self
Set the maximum number of live connections permitted in the pool.
Sourcepub fn idle_timeout(self, idle_timeout: Duration) -> Self
pub fn idle_timeout(self, idle_timeout: Duration) -> Self
Set the idle duration after which a reaper may remove a connection.
This only configures policy. No background task exists until
ConnectionPool::spawn_idle_reaper is called.
Sourcepub fn dispatch(self, strategy: DispatchStrategy) -> Self
pub fn dispatch(self, strategy: DispatchStrategy) -> Self
Set the dispatch strategy.
Sourcepub fn health_check_interval(self, interval: Duration) -> Self
pub fn health_check_interval(self, interval: Duration) -> Self
Set the health check interval.
If set, connections idle longer than this are PINGed before use to verify they are still alive.
Sourcepub fn acquisition_timeout(self, timeout: Duration) -> Self
pub fn acquisition_timeout(self, timeout: Duration) -> Self
Set the maximum time to wait for a connection slot.
If all connections are busy when a command is submitted and a slot
does not free up within timeout, the call returns
RedisError::PoolAcquisitionTimeout. Overrides the bounded
PoolConfig::DEFAULT_ACQUISITION_TIMEOUT. Pass Duration::ZERO for
fail-fast acquisition that never waits; use
Self::disable_acquisition_timeout to wait without a bound.
Sourcepub fn disable_acquisition_timeout(self) -> Self
pub fn disable_acquisition_timeout(self) -> Self
Wait forever for a connection slot, disabling the acquisition timeout.
This restores the previous behavior where a saturated pool blocks the
caller indefinitely. Prefer the bounded
default unless an unbounded wait is genuinely
what you want – an unbounded wait turns pool exhaustion into a silent
hang rather than a surfaced RedisError::PoolAcquisitionTimeout.
Sourcepub fn metrics_recorder(self, recorder: Arc<dyn MetricsRecorder>) -> Self
pub fn metrics_recorder(self, recorder: Arc<dyn MetricsRecorder>) -> Self
Set the recorder that receives pool lifecycle metric events.