NAME
DBIO::Async::Pool - Generic async connection pool for DBIO drivers
VERSION
version 0.900007
SYNOPSIS
my $pool = DBIO::Async::Pool->new(
storage => $storage,
conninfo => { host => 'localhost', dbname => 'myapp' },
size => 10,
on_error => sub { warn $_[0] },
);
my $conn = $pool->acquire->get; # Future resolving to ready connection
my $lease = $pool->_lease($conn); # the borrow's lease, right after the acquire
$pool->release($conn, $lease); # return to pool; a release that comes
# after the connection went on is no-op
# same checkout as acquire; the caller holds it until release
my $txn_conn = $pool->acquire_txn->get;
my $txn_lease = $pool->_lease($txn_conn);
$pool->release($txn_conn, $txn_lease);
DESCRIPTION
Connection pool for DBIO::Async::Storage. Manages a pool of database connections using the idle-list / waiter-queue / capacity mechanics inherited from DBIO::Storage::PoolBase.
This class supplies four additions over PoolBase:
Readiness gating through the "_connection_ready_future" seam -- "acquire" in DBIO::Storage::PoolBase chains every connection it hands out through that seam, and this class answers it with "_await_conn_ready", so the resolved Future does not complete until the connection is actually ready for queries.
Delegation of connection lifecycle to the owning Storage via "_create_connection" and "_shutdown_connection", which call back to "_create_pool_connection" in DBIO::Async::Storage and "_shutdown_pool_connection" in DBIO::Async::Storage.
Delegation of the borrow-time liveness check to the owning Storage via "_idle_connection_alive", which calls back to "_idle_connection_alive" in DBIO::Async::Storage -- so a driver can tell the pool that an idle connection died before it is handed out.
The end of a statement still in flight on a connection the pool closes. "shutdown" in DBIO::Storage::PoolBase, "release" in DBIO::Storage::PoolBase and the rest are core's and not overridden; but a connection is closed through "_shutdown_connection", and that asks the Storage to end what is on its wire first ("STATEMENTS IN FLIGHT" in DBIO::Async::Storage).
Drivers that need a different pool implementation can subclass this or provide their own DBIO::Storage::PoolBase subclass.
METHODS
new
my $pool = DBIO::Async::Pool->new(
storage => $storage, # required
conninfo => $conninfo, # or conninfo_provider
size => 10,
on_error => sub { warn $_[0] },
);
Like "new" in DBIO::Storage::PoolBase, but requires a storage argument (the DBIO::Async::Storage that owns this pool). The storage reference is weakened to avoid a cycle (storage holds pool, pool holds storage). The pool's limits -- acquire_timeout, max_waiters, reset_timeout -- are the storage's async options ("TIMEOUTS AND LIMITS" in DBIO::Async::Storage).
_connection_ready_future
my $future = $pool->_connection_ready_future($conn);
Overrides "_connection_ready_future" in DBIO::Storage::PoolBase, the seam "acquire" in DBIO::Storage::PoolBase chains around every connection it hands out -- freshly spawned, reused-idle, or handed to a queued waiter. Gating lives there and only there, so all three acquire paths and "acquire_txn" in DBIO::Storage::PoolBase are gated identically. Delegates to "_await_conn_ready"; the resolved Future does not complete until the connection is actually ready for queries, which is what makes a driver whose connection construction returns before the async connect finishes (e.g. libpq's PQconnectStart) safe to hand out.
Why this transport overrides the seam instead of inheriting the base default: that default resolves from the readiness side table "_create_ready_connection" in DBIO::Storage::PoolBase fills, which is callback-shaped -- it wires a transport's on_connect / on_error onto a per-connection Future. This transport is poll-shaped: readiness is a question asked of the driver ("_conn_ready" in DBIO::Async::Storage) and waited on with Future::IO->poll on the connection's socket fd, and the future_io seam contract has no connect callbacks to hang such a Future off. Nothing is ever registered in the side table here, so the inherited default would resolve immediately and hand out a still-connecting handle -- the case core's own POD reserves for an override ("a transport whose readiness is not expressible that way").
_await_conn_ready
my $future = $pool->_await_conn_ready($conn);
Returns a Future that resolves to $conn once it is ready for queries. Delegates to the Storage's "_await_conn_ready" in DBIO::Async::Storage. If the Storage reference has been lost (DESTROY path), short-circuits to an immediately-done Future.
_idle_connection_alive
my $alive = $pool->_idle_connection_alive($conn);
Overrides "_idle_connection_alive" in DBIO::Storage::PoolBase, the borrow-time liveness seam "acquire" in DBIO::Storage::PoolBase asks about every idle connection it is about to hand out. Delegates to the owning Storage's "_idle_connection_alive" in DBIO::Async::Storage, the same way "_await_conn_ready" delegates readiness.
Why the override: core asks the pool, and the inherited default answers true without looking. A future_io driver writes a storage adapter and never a pool of its own, so without this delegation a driver that fills the storage seam would never be asked. The storage seam carries the same name and the same contract as core's, so a driver following core's instruction to "override _idle_connection_alive" does exactly that on the class it writes.
A throw from the storage is not caught here. It reaches core's acquire, which counts it as not vouching for the connection, passes it to the pool's on_error and retires the connection -- one rule for every pool, decided in one place.
If the Storage reference has been lost (DESTROY path), answers true without asking: no check, the default's behaviour, just as "_await_conn_ready" short-circuits to a done Future.
_new_waiter
my $waiter = $pool->_new_waiter;
Overrides core's "_new_waiter" in DBIO::Storage::PoolBase seam, which "acquire" in DBIO::Storage::PoolBase calls once for every caller it has to queue, and answers a new, pending DBIO::Async::Future marked with this pool (weakly). Core queues it, wires the cancel hook and settles it.
Why: every Future built on the wait is of the waiter's class, and a plain Future cannot get while pending. With the pool exhausted, a sync storage method -- select_async(...)->get (ADR 0001) -- croaked is not yet complete and does not provide -await>. On a DBIO::Async::Future it waits for its connection and drives Future::IO meanwhile (ADR 0008). If that blocking wait dies -- the built-in loop refusing to sit idle, because the connection is held by the caller itself -- the waiter is withdrawn through "_withdraw_waiter" in DBIO::Storage::PoolBase and failed, and the pool is not left handing a connection to it. Async callers see no difference. The pool's future_class is untouched; only the waiter has this class.
_create_connection
Delegates to the owning Storage's "_create_pool_connection" in DBIO::Async::Storage. The pool tracks the returned connection -- do not push it onto _connections yourself.
_shutdown_connection
Delegates to the owning Storage's "_shutdown_pool_connection" in DBIO::Async::Storage. If the Storage reference has been lost, returns silently (best-effort on DESTROY).
Before the driver closes the connection, the Storage ends whatever statement is still in flight on it ("_abandon_flights_on" in DBIO::Async::Storage): the statement's caller gets a failed Future and the Future::IO poll on the connection's socket is let go of. With or without one, the connection is marked finished, so the transport sends nothing more on it. Core's pool cannot do that -- it knows the connection, not the Future of a statement on it -- and this is the one seam every close goes through: each connection at "shutdown" in DBIO::Storage::PoolBase, which is what the storage's disconnect runs, and each one the pool retires. A connection core does not close is not touched: none in a forked child that inherited the pool ("_verify_pid" in DBIO::Storage::PoolBase), so the parent's statements are not settled there.
_retire_connection
Core's "_retire_connection" in DBIO::Storage::PoolBase, followed by the end of the connection's readiness wait. A connection retired while it is coming up has had the poll of that wait let go of in "_shutdown_connection"; the readiness Future above the poll is core's pool's to hear about, and it hears it here: it is failed once the pool has parked its hand-over, so the caller who waited for the connection has already been told why and the slot the connection held goes to the next caller waiting. "shutdown" in DBIO::Storage::PoolBase fails and cancels what it holds itself, and is left to: during it nothing is failed here.
AUTHOR
DBIO Authors
COPYRIGHT AND LICENSE
Copyright (C) 2026 DBIO Authors
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.