Alpha

These pages are built from turborel-php’s main, turborel 0.0.0. Anything may change from one build to the next: SQL, API, protocol and files alike.

Pools

NAME

Turborel\Pool\Pool: a bounded set of connections a program shares.

SYNOPSIS

final class Pool
{
    public function __construct(Settings|Source|\Closure $source, ?PoolConfig $config = null);
    public function get(): Pooled;
    public function counts(): array;
}

final class Pooled
{
    public function connection(): Connection;
    public function release(): void;
}

final readonly class PoolConfig
{
    public function __construct(array $parts = []);
}

interface Source
{
    public function connect(): Connection;
}

PoolConfig takes its parts by name, each as Appendix C lists them: max, maxIdle, idleTimeout, maxLifetime and wait, in seconds, check and reset.

DESCRIPTION

A pool makes its connections of Settings, a Source, or a closure. get hands out an idle connection that answers its check, else makes one while fewer than max are made, else waits for one to come back, at most wait. counts gives how many are made, handed out and idle, and how many of them are idle. Clones of a pool are the same pool.

A Pooled gives its connection by connection until release, or until it is let go of, gives it back: reset by the protocol's Reset, autocommit off, then the reset statements; of a server that takes no Reset, by one pipeline of ROLLBACK, the Close and Deallocate of each statement prepared, SET SESSION AUTHORIZATION and SET SCHEMA of the login's user, SET TIME ZONE LOCAL, then the reset statements. The check is a Ping, or ROLLBACK of a server that takes none; each waits at most 30 seconds. A connection lost, failing its reset, past maxLifetime, or beyond maxIdle is closed; one idle past idleTimeout, or failing its check, is closed as get meets it.

The pool starts no thread. A get that waits within a Fiber suspends its Fiber, so another may release a connection; outside one, it sleeps a moment at a time until wait runs out.

ERRORS

SQLSTATE SQLCODE When
08001 -919 No connection came back within wait
TB910 -910 A Pooled's connection asked for once it is given back
The source's failure to make a connection

EXAMPLES

use Turborel\Pool\Pool;
use Turborel\Pool\PoolConfig;
use Turborel\Settings\Options;
use Turborel\Settings\Settings;

$settings = Settings::resolveIn(Options::fromUri('turborel://ann@127.0.0.1:7422/?tls_mode=disable'), static fn(string $name): ?string => null);
$pool = new Pool($settings, new PoolConfig(['max' => 1, 'wait' => 0.1]));
$held = $pool->get();
try {
    $pool->get();
} catch (Turborel\TurborelException $none) {
    echo $none->getSqlState(), ': ', $none->getMessage(), PHP_EOL;
}
$held->release();
08001: no connection of the pool's 1 came back within 100ms

STANDARD

[CLIENT Pools].

SEE ALSO

Settings, Pipelines.