RUEN
Package · cpool

CPool

The pool takes care of handing connections out and taking them back, of capping how many exist, of their lifetime and their liveness. What is in the pool it does not know — that is what an adapter of three methods defines. Which is why one pool serves a database, Redis, or anything else.

Requires PHP 8.4+Dependencies noneSwoole optional

Why a pool

The problem. In classic PHP a process served one request and died, so the connection was opened afresh every time and nobody thought about it. A resident worker lives for weeks and serves many requests at once — and now opening a connection per request is expensive, while keeping a single shared one is not allowed: a connection is a socket with a sequential protocol, and two requests would go through it interleaved.

The answer. Keep a set of ready connections and hand them out one at a time. A request takes one, works, gives it back. Connections are reused, their number is capped, and dead ones are replaced.

The problem is the runtime, not the database

A pool is needed not because the database is slow, but because the process stopped dying after the request. Under PHP-FPM a pool is unnecessary and buys nothing — there the process already serves one unit of work at a time.

What this package does

  • Caps the number of connections. A thousand concurrent requests do not become a thousand connections — they queue, and what fails is one request on a timeout, not the database.
  • Hands out live connections. A connection that has been idle is checked before it is handed over and replaced if it died. A database restart stops poisoning the worker.
  • Watches age. Connections older than maxLifetime are retired — that is how the pool keeps up with infrastructure moving underneath it (proxies, failover addresses).
  • Works in both runtimes. Under Swoole — a real pool on coroutines; without it — SingleConnection with the same contract. The calling code does not branch.

What it does not do

The package knows no driver at all. There is no PDO in it, no Redis, no SQL, no protocols. It operates on objects an adapter handed it and can do exactly three things: create, validate, close.

From which the main limitation follows: the pool does not manage connection state. An unclosed transaction or a switched Redis database travels with the connection to the next borrower — that is the caller’s concern.

Who needs it directly

Usually nobody: in an application you use not the pool but what is built on top of it (PPA for the database, winter-redis for Redis). You reach for CPool directly when you need to pool your own source of connections — another DBMS, an external service, a queue broker.

Key concepts

  • ConnectionFactory — the adapter: create(), validate(), close(). The only place that knows about the driver.
  • ConnectionPool — the pool itself: borrow, release, evict.
  • PoolEntry — a borrowed connection together with its timestamps.
  • SingleConnection — the same contract for a runtime without concurrency.
  • PoolPolicy — immutable settings: the cap, timeouts, lifetime, housekeeping.

Next