NAME
DBIO::MySQL::EV::Pool - EV::MariaDB connection pool for DBIO
VERSION
version 0.900007
SYNOPSIS
my $pool = DBIO::MySQL::EV::Pool->new(
conninfo => { host => 'localhost', database => 'myapp', user => 'myapp' },
size => 10,
future_class => 'DBIO::MySQL::EV::Future',
on_error => sub { warn $_[0] },
);
# acquire returns a Future, not a connection: it resolves with a
# connected EV::MariaDB handle -- an idle one, a freshly connected one,
# or the next one released while the pool has no room for another -- and
# fails if the connect is refused.
$pool->acquire->then(sub {
my $mdb = shift;
$mdb->query('SELECT 1', sub {
my ($rows, $err) = @_;
$pool->release($mdb); # back to the pool, or to the next waiter
...
});
return;
})->retain;
# acquire_txn: the same Future; the handle stays yours until you release it
$pool->acquire_txn->then(sub {
my $mdb = shift;
...
})->retain;
"pool" in DBIO::MySQL::EV::Storage builds this pool for you, wired to the storage; constructing one yourself is for tests and tooling.
DESCRIPTION
Connection pool for DBIO::MySQL::EV::Storage. Manages a pool of EV::MariaDB connections, dispatching queries to available connections and queuing when all are busy.
The acquire / release / capacity / shutdown mechanics and the connection-readiness gate are inherited from DBIO::Storage::PoolBase; this class supplies only the EV::MariaDB seam — see "_create_connection", "_new_connection" and "_shutdown_connection" — the fork guard its connections need in a child that resumes the EV loop (Fork safety under "_create_connection", and "_verify_pid"), and the answer to whether a connection's session is gone ("_mysql_connection_gone"), with which a gone connection is reported to the pool so that it is retired, never handed out again ("_mysql_report_if_gone"), and with which an idle connection is vouched for, or not, before the pool hands it out ("_idle_connection_alive"). It also marks the Future a queued caller waits on ("_new_waiter") and answers whether every connection is held by a settling that is running ("_mysql_held_by_callbacks"): what "await" in DBIO::MySQL::EV::Future needs to refuse a blocking wait for a connection that cannot come back while it lasts.
METHODS
_create_connection
Builds one EV::MariaDB connection from the (already-transformed) connect info: a hashref of EV::MariaDB named parameters. Anything else croaks, and so does a hashref that names neither host nor user ("_mysql_refuse_unconnectable"): EV::MariaDB takes no conninfo string, and starts no connect without one of the two, so the handle would never call back and the acquire waiting for it never resolve. The croak reaches that acquire as its failure. The pool tracks the returned connection -- do not push it onto the pool's _connections list yourself.
Delegates to "_create_ready_connection" in DBIO::Storage::PoolBase, which wires the connection's readiness Future for us: on_connect resolves it with the connection, an error before connect fails it, and the Future is registered so the inherited "_connection_ready_future" in DBIO::Storage::PoolBase finds it. A dependent "acquire" in DBIO::Storage::PoolBase Future therefore resolves only on a connected handle, and fails rather than hanging when the connect is refused (core's wiring).
This driver opts into that wiring; it no longer implements it. Choosing it is still explicit — core's _create_connection is a required hook precisely so a pool whose connections are usable the moment the constructor returns does not get the async gate by accident.
Fork safety. EV::MariaDB closes nothing when a forked child exits or drops its copy of a handle, so the parent's sessions survive the child. A child that resumes the EV loop, though, still has every inherited handle's watchers armed on the sockets it shares with the parent, and would read the reply to a statement that was in flight when it forked -- the parent's statement then never completes. The first connection therefore arms one "fork" in EV watcher for the pool. In a child it runs before the child's loop runs anything else, and finishes the child's copy of every handle the child inherited from the parent -- idle ones, and those checked out for a query or pinned for a transaction alike: EV::MariaDB's fork-aware close, which leaves the parent's sessions alone.
It finishes nothing in the process that armed it: that process opened the pool's first connection, so the pool holds nothing it inherited -- also when a child opens the first connection of a pool its parent built but never used.
With a current core it never finishes a connection the child opened itself. A child that uses the pool takes it over ("_verify_pid" in DBIO::Storage::PoolBase): its first acquire drops the parent's connections from the pool, and the child spawns connections of its own. When that happens before the watcher runs -- a child whose first *_async call comes before its loop does, and whose loop then runs inside that call's get -- the pool's connections are the child's, and the watcher leaves them working. The parent's handles the pool dropped are finished all the same: "_verify_pid" keeps a weak reference to each before core lets go of them, and the watcher finishes whichever of them are still alive when it runs -- held by a statement that was in flight, say, or by a transaction. Until the child takes the pool over, the pool's connections are the parent's, and the watcher finishes them.
finish calls back every statement in flight with a "connection finished" error; the callbacks of DBIO::MySQL::EV::QueryExecutor return at once outside the process that issued the statement, so no release, no Future and no caller's callback runs in the child. A callback you passed to a handle yourself (through txn_mdb, say) does get that error in the child. A child that does not run the loop never fires the watcher and needs nothing. The watcher holds the pool weakly and goes away with it, and it never keeps the loop running: an active "fork" in EV watcher alone would keep EV::run from ever returning, so it is armed with keepalive(0) (ADR 0010).
_mysql_connectable
my $ok = DBIO::MySQL::EV::Pool->_mysql_connectable(\%conninfo);
Class or instance method. True when $conninfo is a hashref that gives a host or a user. EV::MariaDB->new starts a connect only then; otherwise its handle stays unconnected and calls back neither on_connect nor on_error (EV::MariaDB 0.08). The one test the pool, the listen connection and a broker's answer share.
_mysql_refuse_unconnectable
DBIO::MySQL::EV::Pool->_mysql_refuse_unconnectable($conninfo);
Croaks unless "_mysql_connectable" holds, loudly instead of leaving a handle that never calls back. The message names the shape and the keys, never a value -- connect info carries the password.
_verify_pid
Extends "_verify_pid" in DBIO::Storage::PoolBase and changes nothing of what core does there. In a process that does not own the pool -- a forked child that inherited it -- it first keeps a weak reference to each connection the pool holds, all of them the parent's, and then lets core drop them. The pool's fork watcher finishes those still alive when the child's loop runs (Fork safety under "_create_connection"); an idle one nothing else holds is simply freed, as core intends.
Nothing is finished here. Core also calls this from shutdown, and so from the pool's DESTROY at a child's global destruction, where EV::MariaDB's callbacks must not run; finishing belongs to the watcher, which runs only in a child that resumes the loop.
_new_connection
Raw-handle seam called by "_create_ready_connection" in DBIO::Storage::PoolBase: constructs the EV::MariaDB handle from named arguments (ours, plus the on_connect / on_error the readiness wiring supplies) and returns it, tracking nothing. The handle is made by "_mysql_new_handle", which keeps passwords out of what it says.
The handle's on_error first reports the connection to the pool when it is gone ("_mysql_report_if_gone"), then runs the on_error the readiness wiring passed in. It asks rather than assumes: EV::MariaDB calls on_error for a connect that failed, and for the error of a secondary result set of a multi-statement query -- which may be the connection lost while those were read, or a statement error on a session that is still there. An idle connection reported gone is retired at once, a checked-out one when it is handed back. EV::MariaDB 0.08 does not watch an idle connection's socket -- the pool looks at it when it is about to hand the connection out ("_idle_connection_alive") -- and it reports a connection lost by a statement through that statement's callback only, never here; those are "_query_async" in DBIO::MySQL::EV::Storage's to report. The handler holds the pool and the handle weakly, so it keeps neither alive.
Being a named method is what lets a test subclass the pool and hand back a fake connection, exercising the readiness wiring with no event loop and no database (t/08-pool-readiness.t).
_mysql_new_handle
my $mdb = DBIO::MySQL::EV::Pool->_mysql_new_handle(%named);
EV::MariaDB->new(%named), with no password in what the handle says about its connection. The one place every EV::MariaDB handle of this distribution is made: "_new_connection" calls it for a pooled connection, "_listen_open" in DBIO::MySQL::EV::Storage for the listen connection -- as a class method, nothing of a pool is used.
Every handle is made with found_rows => 1 unless the connect info says otherwise: CLIENT_FOUND_ROWS is on, as both DBDs have it, so an UPDATE reports the rows it matched and not only those it changed. mysql_client_found_rows=0 in the DSN (found_rows => 0) turns it off.
What a handle says is the client library's text, or the server's, and both quote what they were given: the name of the database they do not know, the host they cannot resolve, the socket they cannot open. A password does not belong in any of those, and ends up in one all the same -- a DSN with a separator gone wrong puts password=... into the name of the database, and the server answers Unknown database '...' with it. So every text the handle hands its on_error is passed on with the passwords shown as ***, the way core masks connect info in a message (DBIO::Util::mask_connect_secrets): the value of a password, passwd, pwd or pass key and the password of a URI. That text is what fails the acquire of a pooled statement and the open of the listen connection, and what the pool's on_error is given. A croak of the constructor is rethrown masked the same way, and there the password the handle was to connect with is masked wherever the text repeats it. The connect info is not kept for it: on_error's text is masked by what is in it. An exception that is no string is rethrown as it came.
What it cannot see is a secret under another name, and a password that is quoted without a key in front of it.
_mysql_socket_nonblocking
DBIO::MySQL::EV::Pool::_mysql_socket_nonblocking($mdb);
Sets O_NONBLOCK on the socket of the connected EV::MariaDB handle $mdb, through a duplicate of the descriptor (the flag belongs to the open file description, so the duplicate is closed again and the handle's socket stays open). Returns true when the flag was set, false when the handle has no socket. Called from "_mysql_new_handle" for every handle, in its on_connect: over TLS it is what keeps the event loop running, over plain TCP it changes nothing observable.
_mysql_connection_gone
my $gone = $pool->_mysql_connection_gone($mdb);
Is the session behind the EV::MariaDB handle $mdb gone? Answered from the handle and its socket alone -- nothing is sent, nothing is read, and it never blocks:
no socket: gone. "socket" in EV::MariaDB is -1 for a handle that never connected or was closed (
finish,close_async), and from the moment an operation found the server gone: the client library gives its socket up then.an operation queued or in flight ("pending_count" in EV::MariaDB): not gone. Its reply is due on the socket, so a readable socket says nothing, and that operation reports a dead connection itself.
otherwise the idle socket must have nothing to read, asked with a zero-timeout
select. A MySQL server never speaks unasked, so a readable idle socket is the server hanging up -- aKILL, a restart,wait_timeout-- and means gone.
Two things are deliberately not consulted. "is_connected" in EV::MariaDB stays true after the server ended the session, and after an operation failed on it (ADR 0010, fact 3). And the error message of a failed statement: its wording is the client library's, or the server's in its lc_messages, and a statement error leaves the session where it was.
Not seen: a peer that vanished without closing its end (a partition). The next statement on the connection meets that, bounded by the TCP stack or a read_timeout in the connect info.
_mysql_report_if_gone
$pool->_mysql_report_if_gone($mdb);
Report $mdb to the pool as dead ("_mark_connection_dead" in DBIO::Storage::PoolBase) when "_mysql_connection_gone" says its session is gone, so the pool retires it instead of handing it out again: at once when it is idle, when it is handed back when it is checked out or pinned. Called for a failed statement, before its connection is released ("_query_async" in DBIO::MySQL::EV::Storage), and from the handle's on_error ("_new_connection"). A handle the pool does not hold -- one it already retired, or one that was never its own -- is ignored, and the report may be made any number of times.
_idle_connection_alive
my $alive = $pool->_idle_connection_alive($mdb);
The borrow-time liveness seam of "acquire" in DBIO::Storage::PoolBase: asked about every idle connection the pool is about to hand out. The answer is "_mysql_connection_gone"'s, the other way round. A connection it does not vouch for is retired by core, which then takes the next idle connection, or opens one. So a session the server ended while its connection sat idle -- a KILL, a restart, wait_timeout -- costs no caller a failed call.
It answers and does nothing else: no report to the pool -- core retires the connection it asked about -- and no operation on the handle. What it costs a borrow is "socket" in EV::MariaDB, "pending_count" in EV::MariaDB and one select with a zero timeout; nothing is sent and nothing is read, so what the server sent stays on the socket.
An idle connection with an operation still queued or in flight is vouched for. Nothing of this transport leaves one behind -- a statement's Future settles only once its last operation was answered -- but a caller that kept the handle can ("txn_mdb" in DBIO::MySQL::EV::TransactionContext). Its reply is due on the socket, so nothing there says the session is gone, and retiring the connection would end that operation.
What is measured. The same question is asked of the listen connection ("_listen_probe" in DBIO::MySQL::EV::Storage): the socket of an idle connection the server KILLed is readable at once (MariaDB 10.11, ADR 0010). On pooled connections it was run against MySQL 8.0.30 and MariaDB 11.8.8 and 11.8.9, over plain TCP and over TLS 1.3 (TLS_AES_256_GCM_SHA384; TLS 1.2 and a Unix socket were not reachable) -- t/32-pool-dead-connection-live.t. A KILL of an idle connection and a wait_timeout are found by this seam on both servers, in both modes: the next call runs without an error on a new session and the pool keeps its size. A healthy idle connection was never taken for gone: its socket was not readable in 12 calls separated by pauses and after 4 s idle, nor when the next call was chained in the callback of the previous SELECT, INSERT or insert_async, or of a CALL with bind values.
A session that is still there can be taken for gone when its idle socket has something to read and pending_count is 0: the call that borrows then runs on a newly opened connection, a reconnect and no error from this seam. What left such a state was a CALL sent as EV::MariaDB's query: for a query, EV::MariaDB 0.08 runs the callback with the first result and reads the rest of the answer -- the closing OK packet, further result sets -- only after that callback returned, and neither pending_count nor any accessor says so. The Future was settled in the callback, so the connection was back in the pool with the rest unread; a call chained in the callback found a readable socket (11 to 19 of 20 behind a load balancer, 1 of 20 in a LAN, over plain TCP, never over TLS 1.3, where libmariadb had read the whole answer before query returned). A statement with bind values after such a CALL failed outright.
The executor sends a CALL without bind values through prepare/execute/close_stmt, where the whole answer is read before the Future settles (DBIO::MySQL::EV::QueryExecutor), and the state is gone: measured again 2026-10-22 (ADR 0010, Measured again (2026-10-22)), the check said "gone" for no healthy connection in any section of t/32-pool-dead-connection-live.t, on MySQL 8.0.30 and MariaDB 11.8.9, plain TCP and TLS. The reachable remainder is a statement a session prepared itself with PREPARE ... FROM 'CALL ...' and ran with EXECUTE as a query: over plain TCP its first chained call took the session for gone (the ADR has the numbers). That remainder is a decided limit and is not built: the maintainer decided on 2026-10-24 not to route the PREPARE/EXECUTE of a hand-written CALL through prepare/execute; the cost is one reconnect of a healthy idle connection, never an error. A multi-statement text cannot get there: the connection does not enable multi statements and both servers refuse it with a syntax error. A CALL, or any statement, the transport builds is not affected.
It narrows the window and does not close it: a session can end after the check, or without the server saying so ("_mysql_connection_gone"). The statement that finds it so fails, and reports the connection ("_mysql_execute" in DBIO::MySQL::EV::Storage).
It is asked only about connections of the process that owns the pool: a forked child's first acquire drops the connections it inherited before any of them is looked at ("_verify_pid").
_new_waiter
The waiter seam of "acquire" in DBIO::Storage::PoolBase: the pending Future a caller waits on that had to be queued, because no connection is idle and the pool has no room for another: it is at its size, or what it has left is taken by a connection it is opening right now. Core's, of the pool's future_class, and told which pool queued it ("_queued_in" in DBIO::MySQL::EV::Future) -- everything chained off it, the Future a blocking call finally waits on included, carries that along. It is what lets "await" in DBIO::MySQL::EV::Future see that it waits for a queued caller, and refuse the wait when no connection can come back while it lasts ("_mysql_held_by_callbacks"). A future_class that is not a DBIO::MySQL::EV::Future is left as core made it.
_mysql_held_by_callbacks
my $stuck = $pool->_mysql_held_by_callbacks;
Is every connection of the pool held by a callback that is running right now, so that none of them can come back before one of those callbacks returns? True when no connection is idle and each one the pool holds has a callback of its own on the call stack and no statement in flight ("_waits_for_callback" in DBIO::MySQL::EV::QueryExecutor). That is a transaction whose coderef, or a then on one of its statements, is running: it gives its connection back only after COMMIT or ROLLBACK, which cannot be sent before the callback has returned. A caller queued for a connection is not served while that lasts, and a blocking wait for it inside those callbacks would never end ("await" in DBIO::MySQL::EV::Future).
False as soon as one connection could still come back: a spawn in flight (the pool counts it against its size, so a caller can be queued behind it although the pool holds fewer connections than its size; the connection it makes may serve that caller), one that is idle or still connecting, one checked out by a statement that is in flight -- its answer releases it -- and one none of whose callbacks is running, whatever holds it.
_shutdown_connection
Closes one EV::MariaDB connection during "shutdown" in DBIO::Storage::PoolBase and when core retires one, then has "forget" in DBIO::MySQL::EV::QueryExecutor drop what the executor kept for it. Errors are swallowed by the caller.
It uses finish, not close_async: close_async croaks without a callback (Usage: EV::MariaDB::close_async(self, cb), EV::MariaDB 0.08) and with not connected on a handle that is still connecting, and core hands this seam connections the pool never counted as connected. finish is synchronous, takes a handle in any state, can be called again, and calls back the statements still in flight with an error.
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.