Class

A pool of interchangeable resources, of which only so many may exist at once.

Introduction#

For database connections, sockets to a service, workers. A coroutine borrows one, uses it alone, and releases it; while all are out, the next borrower waits for one.

• Instances are made by $create when one is needed and none is free, up to $size; they are reused after that.
• Borrowers waiting are served in the order they came: a released instance goes to the one that waited longest.
• An instance that broke (a lost database connection) is given back with discard() instead: the pool forgets it, and makes a new one when needed.
• An instance dropped by its borrower without release() or discard() is noticed when it is destroyed: the pool warns (E_USER_WARNING) and makes a new one in its place. A borrower waiting meanwhile finds out within a second.
• With $window, the pool shrinks to the most instances that were lent at once within the last $window seconds: an idle instance is dropped only while more instances exist than that. A burst keeps its instances for $window seconds, then they go. This is checked when borrow() or release() is called, never by a timer, so memory is returned the next time the pool is used, not when the window ends.
• With $dispose, an instance the pool lets go of (dropped as idle, or given back with discard()) is passed to it, to close or flush it. $dispose must cope with an instance that is already closed or broken, and an exception from it propagates like any coroutine's. It is not called for an instance lost without being given back, which is already destroyed.

Class synopsis#

final class Pool implements \Countable {
    /* Methods */
    public Pool::__construct(
        Closure $create,
        int $size,
        ?float $window = null,
        ?Closure $dispose = null
    )
    public Pool::borrow(float $timeout = PHP_FLOAT_MAX): object
    public Pool::release(object $instance): void
    public Pool::discard(object $instance): void
    public Pool::use(Closure $fn, float $timeout = PHP_FLOAT_MAX): mixed
    public Pool::count(): int
}

Methods#

Examples#

$db = new phasync\Util\Pool(fn () => new PDO($dsn, $user, $password), 10);

// Heavy instances: give memory back 30 s after a burst, and flush what is dropped
$apps = new phasync\Util\Pool(fn () => bootApplication(), 8, window: 30, dispose: fn ($app) => $app->flush());

$rows = $db->use(fn (PDO $pdo) => $pdo->query('SELECT ...')->fetchAll());

$pdo = $db->borrow();          // or by hand
try {
    // ...
} finally {
    $db->release($pdo);
}

See also#

Used in#