Download the PHP package flytachi/winter-cpool without Composer

Winter CPool

📖 Documentation · Quick start · API reference

A connection pool that knows nothing about connections.

The pool handles borrowing, returning, capacity, lifetime and liveness; what is being pooled is supplied by an adapter of three methods. A database adapter opens a PDO and probes with SELECT 1; a Redis adapter opens a \Redis and probes with PING. The pool cannot tell them apart, and that is the point.

Built for long-running PHP: under Swoole it hands a separate connection to every coroutine, and everywhere else it degrades to a single shared connection — the correct answer when a process serves one request at a time.

Installation

Requires PHP 8.4+. ext-swoole is optional: with it you get real pooling, without it the same code keeps working through SingleConnection.

The adapter

Everything driver-specific lives here — three methods, nothing else:

validate() must not throw for "dead" — return false. A thrown probe is treated as dead too, so a sloppy adapter still cannot corrupt the pool.

Borrow and return

borrow() gives back a PoolEntry; the connection itself is $entry->resource. Returning is the caller's job, so finally is the shape to use — or wrap it in a facade that returns automatically at the end of a request (which is what the Winter framework does with a coroutine defer).

When every connection is busy and the pool is at its ceiling, borrow() waits. Past connectionTimeout it throws PoolException::exhausted() rather than opening connection number 10 001 — an exhausted pool is a queue, not an outage of the database.

Outside a coroutine

Without an active Swoole runtime there is nothing to pool: a process serves one unit of work at a time. SingleConnection is the same contract with that assumption baked in.

It still honours maxLifetime and re-validates a connection that has been sitting idle, so a long-lived CLI worker does not wake up holding a socket the server closed hours ago.

Policy

Every knob has a default; pass only what you mean to change.

Housekeeping only runs under Swoole, and only when something enables it — a pool with the defaults costs no timer.

What you get from it

• A hard ceiling. A thousand concurrent requests cannot become a thousand connections; they queue instead, and the database is never the thing that falls over.
• Dead connections are replaced, not returned. Every borrow revalidates (outside the bypass window), so a database restart heals itself instead of poisoning a resident worker.
• Ageing under control. maxLifetime plus jitter retires connections gradually, which matters behind proxies and failover addresses that quietly move.
• One implementation for both runtimes. The calling code does not branch on Swoole.

Fork safety

A fork() copies file descriptors. A child that closes an inherited socket tears down the connection its parent is still using — so after forking, a child calls abandon(), not close():

Both clear the housekeeping timer, and that part is not optional: a Timer::tick callback holds a reference to the pool, so a pool merely dereferenced would stay alive and keep maintaining connections nobody uses.

Observability

active climbing to maximum while borrowers wait is the signal to raise the ceiling — or to find the code path that borrows without returning.

Documentation

The user-facing documentation lives at winterframe.net/packages/cpool (the link picks your language; RU and EN are both complete).

Start here

Guides

Reference

Contributing

Internal technical notes — the connection state machine, what each policy knob changes, and the reasoning behind decisions that are not obvious from the code — live in docs/. Read those before changing how a connection is borrowed or retired.

• Setup, checks and the testing philosophy: CONTRIBUTING.md
• Changes and upgrade notes: CHANGELOG.md
• Reporting a vulnerability, and what the pool does and does not guarantee: SECURITY.md

License

MIT License. See LICENSE.