ConnPool 1.0.12

ConnPool

Connection pooling for .NET — sync & async, dependency-free.

The C# member of poolyglot · Pool once. Speak everywhere.

A generic connection pool for .NET — synchronous (threads) and async/await. Dependency-free (netstandard2.1, standard library only). It pools anything: DB drivers, HTTP clients, SSH sessions, sockets… because the pool knows nothing about connections except what a small ConnectionFactory<T> tells it.

using ConnPool;

var pool = ConnectionPool<MyConn>.FromCallables(MakeConn, validate: IsAlive,
    config: new PoolConfig { MaxSize = 20 });

using (pool)                                  // optional: Open() for warm-up + background sweeper
{
    pool.Open();
    pool.Use(conn => conn.DoSomething());     // acquire -> use -> release (errors handled)
}

This is the C# member of poolyglot: one pooling model, implemented per language, kept API-parallel. Field names, event names, defaults, and CloseReason/BreakerState wire values are identical to the Python (connpool) implementation — switching languages is a syntax change, not a model change.

Install

dotnet add package ConnPool

Targets netstandard2.1, so it runs on .NET Core 3.0+, .NET 5+, and Mono/Xamarin/Unity.

Project layout

src/ConnPool/                 the library (dependency-free)
  Core/            errors, clocks, PooledConnection/CloseReason, Timeout helpers
  Resilience/      CircuitBreaker.cs (breaker + state/config), RetryPolicy.cs (backoff)
  Policy/          PoolConfig.cs, Lifecycle.cs (pure "when must a connection retire?" rules)
  Factories/       ConnectionFactory.cs, AsyncConnectionFactory.cs  <- what YOU implement
  Observability/   Events.cs (PoolListener), Stats.cs (metrics)
  Pools/           ConnectionPool.cs, AsyncConnectionPool.cs, Registry.cs, AsyncPrimitives.cs
tests/ConnPool.Tests/         mirrors src/ (xUnit; 100% line coverage gate)
examples/                     client code - NOT part of the package

Dependency direction is strictly downward (a layer only uses layers listed above it): Core → Resilience → Policy → Factories/Observability → Pools. Everything lives in the single ConnPool namespace, so one using ConnPool; imports the whole public API.

📐 See the architecture diagrams — layering, connection lifecycle, and circuit-breaker states (shared across all poolyglot languages).

What you get

Writing a factory

public sealed class MyFactory : ConnectionFactory<MyConn>
{
    public override MyConn Create()           => MyConn.Connect(...);   // enforce your own connect timeout
    public override bool Validate(MyConn c)   => c.Ping();               // cheap liveness check
    public override void Reset(MyConn c)      => c.Rollback();           // scrub session state on release
    public override void Close(MyConn c)      => c.Dispose();            // default: Dispose() if IDisposable
    public override bool IsFatalError(Exception e) => e is System.Net.Sockets.SocketException;
}

Async: subclass AsyncConnectionFactory<T>, or pass delegates to AsyncConnectionPool<T>.FromCallables(...) (or AsyncCallableFactory<T>.FromSync(...) for sync creators). examples/AdoNetFactory.cs shows one factory that covers every ADO.NET provider.

Borrowing a connection

// delegate form (exception-aware: fatal error / failed validation -> discard, else reuse)
pool.Use(conn => conn.DoWork());
int rows = pool.Use(conn => conn.Count());

// lease form (success-path release on Dispose)
using (var lease = pool.Connection())
    lease.Value.DoWork();

// manual
var conn = pool.Acquire(timeout: 5.0);
try   { conn.DoWork(); }
finally { pool.Release(conn); }

Async mirrors this with UseAsync, ConnectionAsync (await using), and AcquireAsync / ReleaseAsync, each taking an optional CancellationToken.

The Timeout argument is one of three things: omitted/Timeout.Unset → use AcquireTimeout; Timeout.Infinite (or (double?)null) → wait forever; a double (seconds, implicitly convertible) → wait that long (0 = don't wait).

Configuration (PoolConfig)

PoolConfig is an immutable, validated record — construct with an object initializer and copy with with; both validate.

Build, test, run examples

dotnet build src/ConnPool/ConnPool.csproj          # the library (netstandard2.1)
dotnet test                                         # 181 tests (net8.0 + net10.0)
./run_tests.sh                                       # tests under coverage (gate: 100% line + branch)
./run_tests.sh -m                                    # ...also list any uncovered lines / branches
dotnet run --project examples                        # runnable SQLite demo
./lint.sh                                            # Roslyn analyzers as errors (gate) + dotnet format report
./lint.sh -f                                         # ...auto-format

Linting uses the Roslyn analyzers (AnalysisLevel=latest-recommended), gated via dotnet build -warnaserror; dotnet format is warn-only. .editorconfig silences a few rules that conflict with the cross-language design (e.g. PoolError is not renamed to PoolException). CI runs these as a separate lint job.

Limits / extension points

• The breaker guards connection creation. To also trip on request failures, wrap calls with CircuitBreaker.Call().
• The breaker counts consecutive failed creations (one per logical acquire, retries included). A real backend failure or a CreateTimeout firing both count; an acquire-timeout (caller impatience) or cancellation mid-create does not.
• Leak detection is warn-only by design and only runs while the pool is Open() (the maintenance sweep drives it), so registry pools need an explicit Open(), and a warning can lag by up to one MaintenanceInterval.
• Not fork-safe / not process-shared. MaxSize is per-process; create a fresh pool per process.
• Pool size is fixed at construction (PoolConfig is immutable); there is no runtime resize. Use a new pool, or a PoolRegistry keyed by profile.
• Wake-up order of blocked callers is not strictly FIFO.
• Sync Create() can't be interrupted by the pool; give your client a connect timeout.
• Listener hooks are synchronous; push heavy work to a queue.
• A factory's Create() must return a distinct object each call (T is pooled by reference identity); returning a shared/singleton connection is rejected with ConnectionCreateError.
• T must be a reference type (where T : class) — the pool tracks borrow state by object identity.
• Acquire-wait / create-latency percentiles are estimated over the last 1024 samples (bounded memory), not the full history.
• With ValidateIdle on, idle connections being pinged by the background sweep are briefly reserved and count as InUse (not Idle) in Stats() for the duration of that check.

License

MIT — see LICENSE.