Pool Options

Pool options

PoolOptions sets a pool's sizing, timeouts, and which built-in strategies to register. Bind it from the "PoolOptions" configuration section, pass an Action<PoolOptions>, or both — the action runs after binding. The options are validated through the data-annotation pipeline and checked at host startup, so an out-of-range value fails fast.

services.AddPool<SmtpConnection>(configuration, options =>
{
    options.MinSize = 2;
    options.MaxSize = 10;
    options.LeaseTimeout = TimeSpan.FromSeconds(30);
});

Sizing

MinSize

public int MinSize { get; set; }   // default 0, must be >= 0

Items created up front when the pool is built, and the floor Clear() refills to. When MinSize exceeds MaxSize, the pool seeds MaxSize items.

MaxSize

public int MaxSize { get; set; }   // default 100, must be >= 1

Hard cap on items in existence, and therefore on concurrent leases. Set to int.MaxValue for an effectively unbounded pool.

Timeouts

Each timeout defaults to Timeout.InfiniteTimeSpan (wait forever).

LeaseTimeout

public TimeSpan LeaseTimeout { get; set; }   // default infinite

How long a lease waits for an available item before throwing TaskCanceledException. With the default, a saturated pool waits indefinitely.

PreparationTimeout

public TimeSpan PreparationTimeout { get; set; }   // default infinite

How long the readiness check and preparation may take, combined. Applies only when a preparation strategy is registered.

IdleTimeout

public TimeSpan IdleTimeout { get; set; }   // default infinite

How long an item may sit idle before the next lease discards and disposes it instead of reusing it. Eviction is lazy: it happens when a lease meets the stale item, not on a background timer.

Default strategy registration

These flags control whether AddPool registers the built-in factory and preparation strategy. Both default to false.

UseDefaultFactory

public bool UseDefaultFactory { get; set; }   // default false

Registers the default item factory, which resolves TPoolItem from the service provider. Register the item type as well when you set this.

UseDefaultPreparationStrategy

public bool UseDefaultPreparationStrategy { get; set; }   // default false

Registers the default preparation strategy, which reports every item ready without a check.

Named-pool configuration

A named pool reads an optional per-pool section, "{key}_PoolOptions", layered over the shared "PoolOptions" section. The shared section binds first, the per-pool section overrides per property, and the configure action runs last.

UnboundedPoolOptions

The unbounded pool binds UnboundedPoolOptions from the "UnboundedPoolOptions" configuration section through the same validated pipeline. Because a lease never blocks, it drops the bounded pool's capacity controls: there is no MaxSize (a lease never waits for an item) and no LeaseTimeout (there is nothing to wait for). The only cap is on retention.

services.AddUnboundedPool<SmtpConnection>(configuration, options =>
{
    options.MinSize = 2;
    options.MaxIdle = 50;
});

MinSize

public int MinSize { get; set; }   // default 0, must be >= 0

Items created up front when the pool is built, and the floor Clear() refills to. When MinSize exceeds MaxIdle, the pool seeds MaxIdle items, so it never starts over its own retention cap.

MaxIdle

public int MaxIdle { get; set; }   // default 100, must be >= 0

The maximum number of idle items the pool retains for reuse. A return beyond this cap is dropped, and disposed when the item is IDisposable. This bounds memory and server-side load without bounding how many items may be leased concurrently. Zero retains nothing: every return is dropped, for pure allocate-on-lease.

IdleTimeout

public TimeSpan IdleTimeout { get; set; }   // default infinite

How long an item may sit idle before the next lease discards and disposes it instead of reusing it. Eviction is lazy, as in the bounded pool: it happens when a lease meets the stale item, not on a background timer.

PreparationTimeout

public TimeSpan PreparationTimeout { get; set; }   // default infinite

How long the readiness check and preparation may take, combined. Applies only when a preparation strategy is registered.

UseDefaultFactory and UseDefaultPreparationStrategy

public bool UseDefaultFactory { get; set; }              // default false
public bool UseDefaultPreparationStrategy { get; set; }  // default false

Register the built-in item factory and preparation strategy, exactly as the bounded pool's flags do.

A named unbounded pool reads an optional per-pool section, "{key}_UnboundedPoolOptions", layered over the shared "UnboundedPoolOptions" section, the same way named bounded pools layer their configuration.