NAME
DBIO::Async::Storage - Future::IO transport backend for DBIO async storage
VERSION
version 0.900007
DESCRIPTION
The future_io async backend (ADR 0030): one loop-agnostic transport that drives a driver's own non-blocking DBD binding through Future::IO. The event loop is chosen by loading a Future::IO::Impl::* adapter (see "FUTURE::IO IMPLEMENTATIONS"), not by picking a distribution.
The Model-B orchestration -- connect-info normalisation, the CRUD runner ("_run_crud" in DBIO::Storage::Async with its pooled and pinned runners), INSERT returned-columns mapping, "txn_do_async" in DBIO::Storage::Async bracketing through the generic DBIO::Storage::Async::TransactionContext, and the "pipeline" in DBIO::Storage::Async scaffold -- is inherited concretely from DBIO::Storage::Async (ADR 0030 §4). This class supplies only the transport: the Future::IO query execution ("_query_async" / "_query_async_pinned" over "_await_query_result"), the Future implementation ("future_class") and the connection pool ("pool"), plus the DB-specific seam hooks a concrete DBD subclass fills in.
METHODS
future_class
Returns 'Future' -- this backend uses Future from CPAN.
transport_capabilities
my @caps = DBIO::Async::Storage->transport_capabilities; # ('on_connect_replay')
Class method (see "transport_capabilities" in DBIO::Storage::Async). Declares the named transport capabilities this future_io transport provides, so "_async_storage" in DBIO::Storage::DBI lets an async extension layer that declares a matching required_transport_capabilities compose onto it (and croaks on a shortfall rather than silently dropping the feature).
This transport declares on_connect_replay: its pool (DBIO::Async::Pool, a DBIO::Storage::PoolBase) drives core's "_setup_pool_connection" in DBIO::Storage::Async on every freshly-spawned connection, and the { dbh => $dbh } connection shape is handled by the base _run_pool_connect_statement -- so each pooled async connection replays the owning sync storage's on_connect_do/on_connect_call (and the on_disconnect_* actions at shutdown) end to end. A concrete DBD subclass inherits this obligation for free.
pool
Returns the DBIO::Async::Pool connection pool, created lazily on first access. Fed the per-spawn conninfo_provider when an AccessBroker is attached (see "_conninfo_provider" in DBIO::Storage::Async), otherwise the static conninfo.
Building it is for whatever starts work -- a query, a transaction. What ends work does not call this: a statement that settles talks to the pool it was dispatched with ("STATEMENTS IN FLIGHT"), so a storage that was disconnected is not given a new pool by something that merely finished.
_async_broker_conninfo
my $conninfo = $storage->_async_broker_conninfo($mode);
AccessBroker seam (see "ACCESSBROKER CONSUMPTION" in DBIO::Storage::Async), called through "_conninfo_provider" in DBIO::Storage::Async for every new connection -- each pool spawn, and a driver's listen connection: ask the attached broker for its current connect info -- anew each time, so rotated credentials reach the next connection -- and return one storage-native conninfo built from it. The broker's answer may come in any of these shapes:
A DBI-form arrayref
[ 'dbi:...', $user, $password, \%attrs ], as DBIO::AccessBroker::Vault answers, and DBIO::AccessBroker::HostBound over it. The DBIO-private attributes --async,quote_names, the storage options and the rest -- are stripped the way core strips them from a direct connect ("connect_info" in DBIO::Storage::Async): a Vault broker selects this transport withdbi_attrs => { async => 'future_io' }, andasyncis no DBD attribute. A fifth element\%extra_attributesjoins\%attrs, the later winning, as on the sync storage.pool_sizeis dropped: the pool was sized from the answer when the broker was attached, and it is no DBD attribute either.A hashref of connection parameters --
dbname,host,port,user,password-- as DBIO::AccessBroker::Static answers, and DBIO::AccessBroker::HostBound over it. Read the way the sync storage reads it:dbname,hostandportbecome the DSN,userandpasswordthe user and password, every other key a DBD attribute; then as a DBI-form answer.dbname,hostandportare never DBD attributes, and an empty one --undef, as Static answers a part not given, or the empty string -- is as none given. Adbnamethat starts withdbi:is the DSN, with or without an owner; ahostorportset beside it cannot be put into it and croaks, naming the keys (core ADR 0057). Otherwise only the owning sync storage ("_owner_storage" in DBIO::Storage::Async) knows which DBD driver the parameters are for, so the DSN is built by its_dsn_from_connect_params(DBIO::Storage::DBI). A backend without an owner -- constructed directly rather than reached through a schema connected with{ async => 'future_io' }-- croaks here, saying so.This transport's own connect info: a hashref with a
dsn, or a[ \%conninfo, \%opts ]pair -- what a broker written for one transport answers fromconnect_info_for_storage. Taken as it is, as "connect_info" in DBIO::Storage::Async takes it.
The result goes through the driver's _normalize_conninfo -- for the first two shapes as the DBI form [ $dsn, $user, $password, \%attrs ], exactly what a direct connect with a DSN hands it -- and core's pool_size split. This base knows no DBD; what the driver's connect receives is the driver's shape.
Connection settings given beside the broker (connect($broker, \%options)) reach every connection built from a DBI-form or connection-parameter answer: the DBD attributes among them ("_access_broker_call_attributes" in DBIO::Storage::Async) are merged into \%attrs by _merge_access_broker_settings -- a setting given in both places must have the same value, or this throws naming it. Core keeps them empty unless the transport declares broker_connect_options, which this base does not; a driver that declares it gets the merge from here. They cannot be merged into a transport's own connect info, whose attributes are the driver's shape: that combination croaks rather than drop them.
Any other answer croaks, naming its shape -- types and hash keys, never the values, which carry the password.
Without a broker attached it croaks saying so. The provider outlives a broker detached through "clear_access_broker" in DBIO::Storage -- on the storage, and in a pool built with it -- and nothing is answered then, which is no broker's answer and is not reported as one. Core's provider refuses with the same words before it asks ("_conninfo_provider" in DBIO::Storage::Async); this check is the seam's own, for a call that does not come through the provider.
_query_async
my $future = $storage->_query_async($sql, $bind, $bind_attrs);
Transport override: execute a query on a freshly-acquired pooled connection, releasing it once the statement has settled. $bind_attrs is optional and for the trace alone ("TRACE"); the wire gets the bare $bind.
The Future it returns is the caller's own. The statement's Future -- the flight: the Future::IO poll and the collect chained onto it -- is held by the storage until it settles, and so is the wait for the pool before it (see "STATEMENTS IN FLIGHT"). A caller may keep the returned Future, chain on it, ->get it -- it is of the flight's class and runs its loop -- or let go of it: the statement is collected and its connection handed back either way. The connection is back in the pool before the caller's callbacks run, so a query issued from one finds it.
Receives SQL in the sql_maker ?-placeholder dialect (the contract of the core seam) and shapes it into the driver's own dialect internally, up front, through "_transform_sql" in DBIO::Storage::Async before the query reaches the wire. Callers do not pre-shape: the ADR 0032 §6 sequencing is finished and core's orchestration has no _transform_sql call site left.
A ?->$N-style rewrite must nonetheless be idempotent -- already-shaped SQL (no bare ? left to touch) passes through unchanged, and a ? inside a quoted literal is never touched. That is a standing property of a seam that runs on every single query, not a leftover of the transition window that motivated it.
The dispatch goes through core's "_seam_future" in DBIO::Storage::Async, and a die there becomes a failed Future, the pattern core documents. The release hangs off the query Future, and that Future exists only once "_await_query_result" has returned. A dispatch that croaks synchronously -- another operation is in progress, not connected -- never gets that far, so without the guard the connection would stay checked out, and a pool of N would be wedged for good after N such calls. The base "_await_query_result" wraps its own dispatch in Future->call, but a driver may override that seam and owes no such wrapper, so the guarantee lives here. As a failed Future the die takes the same release as every other outcome, and the caller sees the dispatch's own error. A driver's seam that returns no Future at all -- undef, a plain value -- fails the same way, with an error naming the backend class and the seam.
A query that fails -- whether its dispatch died or the Future failed later -- asks the driver whether it took its connection with it ("_conn_error_is_fatal"), before the release runs: the callback "_mark_dead_on_fail" builds is registered ahead of the one "_release_on_ready" builds, and a Future runs its callbacks in the order they were registered. A connection the driver answers dead for is reported to the pool ("_mark_connection_dead" in DBIO::Storage::PoolBase), so the release retires it instead of putting it back on the idle list. The caller still sees the query's own error.
A query cancelled while in flight retires its connection too. The cancel -- on the returned Future, or on any Future chained on it, which passes the cancel down -- reaches the flight ("_let_go") and drops the Future::IO poll, but the statement is on the server and its result on its way, unread. Handed back as it was, the connection would go to the next borrower, whose query the DBD then refuses (DBD::Pg: another command is already in progress). The base cannot read that result without the driver, nor cancel the statement on the server, so the callback "_abandon_on_cancel" builds reports the connection dead to the pool before the release runs -- a Future runs its on_cancel callbacks before any on_ready one -- and the release retires it; a caller queued for the slot gets a fresh connection. That is what "_query_async_pinned" does with a cancelled statement ("THE PINNED STATEMENT QUEUE"). "_conn_error_is_fatal" is not asked: a cancel is no failure, and says nothing about the session. A cancel that comes while the caller still waits for the pool dispatched nothing and retires nothing.
A statement that outlasts the connect option statement_timeout is cancelled in flight the same way, and its caller's Future fails with the timeout ("TIMEOUTS AND LIMITS").
Draining instead -- keep the connection, await "_collect_result" and throw the result away -- is not done. How far the cancel reached into the driver's collect is unknowable here, a result can take as long as the query the caller just gave up on, and the pool slot would be held for all of it.
A query whose connection is closed under it -- the storage disconnected, the pool shut down -- fails where that happens; see "STATEMENTS IN FLIGHT".
The callbacks below are handed the pool the connection was acquired from, and talk to that one. None of them asks "pool", which would build a pool for a statement that ends after its storage was disconnected.
_abandon_on_cancel
my $cb = $storage->_abandon_on_cancel($conn, $pool);
$query_future->on_cancel($cb);
Build the callback a pooled query Future runs when it is cancelled in flight: report $conn dead to $pool, the pool it was acquired from ("_mark_connection_dead" in DBIO::Storage::PoolBase), so the release that follows retires it rather than idling it with an unread result on it (see "_query_async"). A named sub for the reason "_release_on_ready" is one: it closes over the connection and its pool, not over the SQL and the caller's bind arrayref (ADR 0044).
The callback never dies. A Future runs its on_cancel callbacks from inside cancel, with no eval of its own: a die would escape into the caller's cancel and leave the Future unmarked, the release never run. A failing report is warned about instead.
_release_on_ready
my $cb = $storage->_release_on_ready($conn, $pool, $caller, $lease);
Build the pool-release callback for a query Future: $conn goes back to $pool, the pool it was acquired from, and then $caller -- the Future "_query_async" handed its caller -- takes the statement's outcome. In that order: the connection is in the pool again when the caller's callbacks run.
$lease is the lease of the borrow ("_lease" in DBIO::Storage::PoolBase, asked for right after the acquire resolved) and is handed to the pool's release as its second argument. A statement that completes after its connection went on -- handed to a queued caller, borrowed again from the idle list -- then releases a borrow that is over, and the pool takes nothing from it: silently, so the one session is never on two callers' hands. Optional: without a lease the release is made without one and is taken as the current holder's.
A named sub, deliberately not a closure inside the ->then(sub {...}) acquire chain (ADR 0044): the callback is created HERE, in a sub whose pad dies when this sub returns, so the bind arrayref lives only until dispatch, not for the whole flight of the query. A callback created inside the ->then closure would be retained by the query Future for the flight ("_await_query_result" and its Future::IO watcher hold it while the connection socket is polled) and would pin that closure's pad -- and $bind -- alive via CvOUTSIDE.
_mark_dead_on_fail
my $cb = $storage->_mark_dead_on_fail($conn, $pool);
$query_future->on_fail($cb);
Build the callback a failed query Future runs to ask "_conn_error_is_fatal" about $conn, and to report the connection to $pool ("_mark_connection_dead" in DBIO::Storage::PoolBase) when the answer is true. $pool is the pool the statement was dispatched with: the one a pooled query acquired from, and for a pinned statement the pool the storage had when it went out -- none, for a storage that never built one, and then there is nobody to tell. A named sub for the reason "_release_on_ready" is one: built here, the callback closes over the connection and its pool, not over the SQL and the caller's bind arrayref (ADR 0044).
"_query_async" registers it before the release callback, so the pool is told before the connection comes back and the release retires it rather than idling it. "_query_async_pinned" registers it on its own; the pinned connection's one hand-back is its holder's.
The callback never dies. It runs inside the completion of the query Future, where a die would escape into whatever completed that Future and skip every callback registered after it -- the release among them. So the seam is called inside an eval: a throw counts as dead, and goes to the pool's on_error (a warn should that die too, or with no pool to tell). A failing report to the pool is warned about as well. Nothing of either reaches the query Future, which keeps its own error.
_query_async_pinned
Transport override: like "_query_async" but runs on the supplied pinned connection and does not release it -- used for queries inside a pinned transaction. Shapes the incoming ?-dialect SQL internally through "_transform_sql" in DBIO::Storage::Async exactly as "_query_async" does.
Statements on one connection are serialised: a statement is dispatched only once the one before it on the same connection has settled, so a caller may issue several without awaiting each. The returned Future is the caller's; see "THE PINNED STATEMENT QUEUE". The statement's own Future is held by the storage for the flight, as a pooled query's is, so a statement whose Future nobody keeps is still collected, and one whose connection is closed under it fails there ("STATEMENTS IN FLIGHT").
A failed query asks "_conn_error_is_fatal" about the pinned connection, as in "_query_async". A true answer reports it to the pool, and the connection's one hand-back then retires it: for a transaction that is core's finalizer, whose release comes after the ROLLBACK ("txn_do_async" in DBIO::Storage::Async). So a transaction whose connection died under it fails as before, and the connection is not handed out again. The dispatch goes through "_seam_future" in DBIO::Storage::Async here too, so a driver's own "_await_query_result" that dies, or returns no Future, is asked about as well: it comes back as a failed Future, like every other failure of this seam.
_abandon_flights_on
$storage->_abandon_flights_on($conn);
The pool is about to close $conn: end what is still in flight on it (see "STATEMENTS IN FLIGHT"). Called by "_shutdown_connection" in DBIO::Async::Pool for every connection core's pool closes, before the driver's "_shutdown_pool_connection"; a driver that brings a pool of its own calls it from the same place.
Each statement in flight on $conn has its caller's Future failed and its poll let go of, in the order they were dispatched. And a hashref connection is marked as finished, whether or not anything is on it: it gets a pinned statement queue that only refuses, or the one it has is set to. What waits in it fails unsent as the flight is let go of, and whatever is issued on the connection later fails unsent as well -- nothing more is handed to "_submit_query" for it. A connection that is no hashref has no place for the mark and is left as it is.
Does nothing at all in global destruction. Never dies: it runs inside the pool's teardown, where a die would skip the close of the connection.
async_option_names
sub async_option_names { ($_[0]->SUPER::async_option_names, qw( my_option )) }
The options this transport adds to core's: statement_timeout and max_pending_pinned. A driver adapter that declares options of its own extends this list through SUPER::, so these two stay declared.
_await_readable
my $future = $storage->_await_readable($conn);
Returns a Future that becomes ready once the connection's socket is readable -- in the process that asked. A fork copies the event loop's watch list with everything else, and the socket is as readable in the child as in the parent, so the child's loop resolves the parent's poll if it turns. There the returned Future stays pending for good, and nothing chained onto it runs: no "_collect_result", which would read the parent's answer off the shared socket and leave the parent waiting for it, no release, no settled Future, no callback of the parent's. That holds for every poll made here -- the first one of a statement, the one a driver makes to wait for the rest of a result, a connection still coming up -- because all of them are made here. The listen watch loop refuses a poll from another process on its own ("THE LISTEN WATCH LOOP").
The single seam through which this transport touches Future::IO: a concrete driver's "_collect_result" that must wait for more of a result also calls this rather than re-implementing the fd wrapping. The filehandle poll needs is supplied by "_conn_poll_fh". Its counterpart is "_let_go", the single place where the transport gives a poll up. When a poll resolves, and what a callback run from it may do, is the Future::IO implementation's; see "FUTURE::IO IMPLEMENTATIONS" for what the built-in one and the IO::Async one do that a caller meets.
A driver that re-polls this way recurses as $self->_collect_result($conn) -- the seam takes the connection and nothing else (ADR 0044). Carrying the SQL and the bind arrayref into the re-poll callback would pin the caller's binds for as long as the result keeps arriving, which is precisely the lifetime ADR 0044 ends at dispatch.
_let_go
$storage->_let_go($future);
Stop waiting for $future: cancel it, unless it has settled already. The single place where this transport gives up on something it awaits, as "_await_readable" is the single place where it starts to: a statement in flight whose caller cancelled it or whose connection is being closed ("STATEMENTS IN FLIGHT"), and whatever the listen watch loop awaited when it is stopped ("_listen_unwatch") -- a poll, a timer or a drain query. Future carries the cancel down the chain to the Future::IO poll or timer at its head, and what the implementation then does with its watch is the implementation's: the built-in one drops it in the cancel, and its round dies when that cancel came from the callback of a poll in front of this one; Future::IO::Impl::IOAsync keeps the watch until the socket next turns readable ("FUTURE::IO IMPLEMENTATIONS").
A Future that cannot be cancelled is left alone.
_conn_poll_fh
my $fh = $storage->_conn_poll_fh($conn);
The stable poll filehandle for $conn, created lazily on first use and cached on the connection for its whole life. Future::IO->poll requires a real filehandle, but a driver's "_conn_fileno" hands back the raw integer socket fd (e.g. DBD::Pg's pg_socket). The '+<&' open mode dups that fd (via dup(2)) into an independent filehandle, so closing this handle never touches the driver's own socket.
The dup is cached per connection for a correctness reason, not merely for speed. Future::IO watches the filehandle and, once the poll resolves, unwatches it by its fileno -- but its impls mark the Future done before they unwatch. A fresh-dup-per-poll handle closed the moment its poll resolved would already be gone when the loop unwatches: $fh->fileno returns undef, the loop's watch table is corrupted, and the freed fd -- reused by the next dup -- collides with the stale watch (observed as pg_ready: No asynchronous query is running on the following query). Reusing one stable handle for every poll on a connection keeps the fileno valid across the whole watch/unwatch cycle. The dup fd dies with the connection it mirrors, when $conn is torn down.
Cached on the connection hashref under the reserved key _dbio_async_poll_fh; a driver whose connection is not a hashref must supply its own caching.
_await_conn_ready
my $future = $storage->_await_conn_ready($conn);
Returns a Future that resolves to $conn once the connection is ready for queries. Uses "_conn_ready" to check readiness and "_await_readable" to wait on the fd from "_conn_fileno" when not yet ready.
While it waits, a hashref connection carries what the wait consists of under the reserved key _dbio_async_ready (next to _dbio_async_poll_fh): the Future returned here and the poll it is currently waiting on, both held weakly, and gone as soon as the Future settles. That is what lets "_abandon_flights_on" end the wait when the pool closes the connection before it came up -- a retirement while it is coming up: the poll is let go of ("_let_go"), so the loop does not go on watching the dup of a closed connection's socket and nobody asks the closed connection whether it is ready, and "_retire_connection" in DBIO::Async::Pool then fails the returned Future, which is how the pool learns to hand the slot on. A connection that is no hashref has no place for it; its wait is left to the pool's own cancel, as before. The optional third argument is the wait's own bookkeeping, passed on by the rounds after the first.
_await_query_result
my $future = $storage->_await_query_result($conn, $sql, $bind);
Submits the query via "_submit_query", waits for the connection socket to become readable via "_await_readable", and collects the result via "_collect_result". Returns a Future resolving to the result rows.
$sql and $bind are consumed by the dispatch ("_submit_query") and by nothing after it: the collect callback is built by "_collect_on_readable", which forwards only $conn. That is what keeps the bind arrayref's life inside the dispatch (ADR 0044) even though the readable-Future holds a callback for the whole flight -- see "_collect_on_readable" for the mechanism. The Future->call wrapper itself retains nothing: Future invokes the code and returns the Future it produced without keeping the code reference, so once no surviving callback pins this closure through CvOUTSIDE, its pad -- and with it $sql and $bind -- is freed as soon as the dispatch returns.
_collect_on_readable
my $cb = $storage->_collect_on_readable($conn);
Build the result-collecting callback for a dispatched query. A named sub, deliberately not a closure inside the Future->call(sub {...}) dispatch block (ADR 0044), for the same reason "_release_on_ready" is one: the callback is created HERE, in a sub whose pad dies when this sub returns, so it closes over $conn alone.
A callback created inline in the dispatch block instead would be retained by the pending "_await_readable" Future for the whole flight of the query -- until the connection socket becomes readable -- and would pin that block's pad through CvOUTSIDE, keeping $sql and the caller's $bind arrayref alive with it. That is the half of ADR 0044 one level below "_release_on_ready": the binds are serialised onto the wire by "_submit_query" and no callback needs them again, so no callback may hold them.
_listen_delay
my $f = $storage->_listen_delay($seconds);
Core listen seam ("_listen_delay" in DBIO::Storage::Async): the reconnect backoff timer, and the pacing timer of the watch loop. Returns Future::IO->sleep($seconds) as it is -- pending on return, resolved by whichever loop drives Future::IO, and cancellable: cancel drops the timer (the built-in implementation removes it from its alarm list), which is what core relies on when it cuts a backoff short.
The Future is not re-wrapped into "future_class". For this transport's 'Future' it already is one -- every Future::IO implementation returns a Future subclass -- and a wrapper would only stand between core's cancel and the timer. A subclass naming a different "future_class" gets a Future-API object here, as it already does from "_await_readable".
_listen_poll_interval
my $seconds = $storage->_listen_poll_interval; # undef: socket-driven
The watch mode switch (see "THE LISTEN WATCH LOOP"), asked once each time "_listen_watch" starts. undef, the default, selects socket-driven watching; a positive number of seconds selects timer-driven watching at that interval. Anything else fails the watch, which core reports and heals from like any other failed arm -- loudly, on every attempt -- instead of a zero interval spinning the loop. A driver may back it with an accessor of its own; a change applies from the next watch, that is the next listen connection.
_listen_watch
$storage->_listen_watch($conn);
Core listen seam ("_listen_watch" in DBIO::Storage::Async), implemented once for every Future::IO transport: start the watch loop described in "THE LISTEN WATCH LOOP" on the listen connection $conn, which must be a hashref. Returns at once; the loop runs from the event loop. In socket mode the poll handle is dup'd here, so a connection without a usable socket fails the arm itself -- core reports it and heals. A watch already running on $conn is stopped first.
_listen_unwatch
$storage->_listen_unwatch($conn);
Core listen seam ("_listen_unwatch" in DBIO::Storage::Async): stop the watch loop on $conn. The watch state is taken off the connection first, then the poll, timer or drain Future it awaited is let go of ("_let_go"); anything that still resolves afterwards is ignored. Once this returns, the loop dispatches nothing and reports nothing for $conn, and holds nothing that keeps $conn alive. A connection that is not being watched is left alone.
_notify_send
my $f = $storage->_notify_send($channel, $payload);
Core listen seam ("_notify_send" in DBIO::Storage::Async): send one notification on a pooled connection. Runs the SQL and bind values from "_notify_sql" through "_query_async", which shapes the ? placeholders into the driver dialect ("_transform_sql" in DBIO::Storage::Async) and releases the connection afterwards. Resolves with whatever that query resolves with.
_txn_context_class
my $class = $storage->_txn_context_class; # DBIO::Async::TransactionContext
The pinned-connection context "txn_do_async" in DBIO::Storage::Async hands to its coderef. Narrows core's generic DBIO::Storage::Async::TransactionContext default to this dist's DBIO::Async::TransactionContext, so every future_io adapter gets the future_io context without naming it.
_txn_conn_accessor
my $key = $storage->_txn_conn_accessor; # 'txn_conn'
The constructor key "txn_do_async" in DBIO::Storage::Async passes the pinned connection under when building the "_txn_context_class". Stated next to the class it belongs to, so a context that ever changed its key would change both halves in one place.
_submit_query
$storage->_submit_query($conn, $sql, $bind);
Driver seam: send one query on the connection $conn without waiting for its result. Called by "_await_query_result" for every query of "_query_async" and "_query_async_pinned", with $sql already shaped into the driver's dialect by "_transform_sql" in DBIO::Storage::Async and $bind an arrayref of bind values (empty when there are none). The return value is ignored: once this returns, the base waits for the connection's socket to become readable ("_await_readable") and then asks "_collect_result" for the result.
"_collect_result" is handed $conn alone, so whatever it needs of the query in flight -- a statement handle, say -- the dispatch leaves on $conn, never the SQL or the bind arrayref: those end with the dispatch (ADR 0044; see "_collect_on_readable").
A die here fails the query's Future with that error, which then takes the path of any failed query: "_conn_error_is_fatal" is asked about $conn, and a pooled connection is released.
The base croaks until a driver provides it.
_collect_result
my $future = $storage->_collect_result($conn);
Driver seam: read the result of the query "_submit_query" sent on $conn. Called once the connection's socket has become readable after the dispatch, through the callback "_collect_on_readable" builds, with the connection and nothing else (ADR 0044). Returns a Future of the query's result, in the shape "_query_async" in DBIO::Storage::Async promises its caller: the raw rows of a statement that returns rows, the affected-row count of one that does not.
A readable socket does not mean the whole result has arrived. When it has not, the driver waits for more with "_await_readable" and calls itself again as $self->_collect_result($conn), rather than blocking on the rest.
A failed statement dies here or fails the returned Future; either way the query's Future fails, and "_conn_error_is_fatal" is asked about $conn.
It is not called for every statement "_submit_query" sent: one cancelled in flight, or whose connection was closed under it, is never collected. Leave nothing on $conn that only a later call here would clear.
The base croaks until a driver provides it.
_normalize_conninfo
my $info = $storage->_normalize_conninfo($info);
Driver seam: turn connect info into this transport's own shape. Core's "connect_info" in DBIO::Storage::Async calls it with the connect info the schema was connected with, the DBIO-private attributes already stripped -- for a DSN connect, typically the DBI form [ $dsn, $user, $password, \%attrs ]. "_async_broker_conninfo" calls it with each answer of an AccessBroker, in that DBI form or as a [ \%conninfo, \%opts ] pair already in the transport's own shape.
It returns [ $conninfo, \%opts ]: core takes a pool_size key out of a hashref $conninfo to size the pool, and the pool hands $conninfo to "_create_pool_connection". Connect info already in that shape, and the broker form [ $broker ] / [ $broker, \%options ], come back unchanged: core looks for the broker only after this seam has run.
Where core's default passes everything through as it is, this base croaks until a driver provides the seam: an abstract transport has no connection shape of its own to pass anything through to.
_create_pool_connection
my $conn = $storage->_create_pool_connection($conninfo);
Driver seam: open one connection for the pool from $conninfo, and return it. Called through "_create_connection" in DBIO::Async::Pool whenever the pool spawns a connection. $conninfo is the first half of what "_normalize_conninfo" returned, its pool_size taken out by core; with an AccessBroker attached, a fresh one from "_async_broker_conninfo" for every spawn, so rotated credentials reach the new connection.
The pool counts the connection and hands it out; do not register it anywhere yourself. Right after this returns, the pool replays the owning storage's on_connect_do / on_connect_call on it (see "transport_capabilities"): core's _run_pool_connect_statement runs them on a { dbh => $dbh } hashref, which is also what the base keeps its per-connection state on ("_conn_poll_fh"). The pool hands the connection out only once "_conn_ready" answers true.
A die fails the caller's borrow with that error.
The base croaks until a driver provides it.
_shutdown_pool_connection
$storage->_shutdown_pool_connection($conn);
Driver seam: close one connection the pool is done with -- when it shuts down (the storage's disconnect), and whenever it retires one: a connection reported dead ("_conn_error_is_fatal"), an idle one "_idle_connection_alive" did not vouch for, one whose readiness or connect actions failed. Called through "_shutdown_connection" in DBIO::Async::Pool, once per connection. The connection may already be dead; a die here is swallowed by the pool.
A statement may be on the connection's wire when this is called -- one in flight when the storage was disconnected. The base has ended it by then: its caller's Future has failed and nothing waits for the socket any more ("_abandon_flights_on"). The driver closes the handle as it would an idle one; it is not asked to cancel the statement on the server. Nothing is handed to "_submit_query" for a hashref connection afterwards.
The base croaks until a driver provides it.
_conn_ready
my $ready = $storage->_conn_ready($conn);
Driver seam: is $conn ready for queries? A boolean, asked by "_await_conn_ready" each time the pool is about to hand the connection out ("_connection_ready_future" in DBIO::Async::Pool) -- freshly spawned, idle, or passed to a queued caller. While it answers false, the base waits for the socket to become readable ("_await_readable", on the fd from "_conn_fileno") and asks again; the caller gets the connection once it answers true. A die fails the borrow, and the pool retires the connection.
A driver that connects blocking, as DBI->connect does, answers true for any live handle.
The base croaks until a driver provides it.
_conn_fileno
my $fd = $storage->_conn_fileno($conn);
Driver seam: the connection's socket as a raw integer file descriptor -- for DBD::Pg, $dbh->{pg_socket}. Asked by "_conn_poll_fh" the first time the base has to wait on $conn, and not again: the base dups the fd into a filehandle of its own, cached on the connection, and polls that, never the driver's socket itself. An fd that cannot be dup'd -- undef, or closed -- fails the query, borrow or listen watch that needed it.
The base croaks until a driver provides it.
_conn_error_is_fatal
sub _conn_error_is_fatal {
my ($self, $conn, $error) = @_;
... # the handle's local state, or the error itself -- no round trip
return $dead;
}
Driver seam: did the query that just failed on $conn with $error leave the connection dead -- its server session gone, its socket closed, the protocol out of step? Asked by "_query_async" and "_query_async_pinned" for every query Future that fails, with the connection it ran on and the Future's failure: $error is the message, and any category and details the Future failed with follow it as further arguments. Never asked about a query that succeeded, or that was cancelled.
A true answer reports $conn to the pool ("_mark_connection_dead" in DBIO::Storage::PoolBase) before the connection is handed back, so the release retires it instead of putting it back on the idle list, and a caller queued for its slot gets a freshly spawned connection. A transaction's connection is covered alike: core hands it back through the same release once the transaction has ended. Without the report the pool cannot tell -- it would hand the dead connection to the next caller, whose query then fails the same way. The failed query itself is not retried; its caller sees its own error.
The default answers false: nothing is reported, and a connection goes back to the idle list whatever its query failed with -- the behaviour from before the seam. Only the driver can tell a connection-level error from a statement error the session survives, and the DBDs disagree on how it shows (core ADR 0047, addendum 2026-09-27: report, not probe). So a driver answers from what is already there, the handle's local state or the error itself: for DBD::Pg, libpq has given up the socket (pg_socket is -1); for DBD::mysql and DBD::MariaDB, the error code on the handle is a lost connection (2006, server has gone away; 2013, lost connection during query). It runs in the failure path of a query, from inside the event loop, so it must never block and never send anything to the server: no ping, no round trip.
A throw counts as dead -- the rule core applies to a throwing "_idle_connection_alive" in DBIO::Storage::PoolBase -- and goes to the pool's on_error, so a broken classification is not silent. It goes nowhere else: the query keeps its own error, and the connection is still handed back exactly once (see "_mark_dead_on_fail").
The listen connection is asked about too, when a drain query on it fails (an emulation's "_listen_drain" runs through "_query_async_pinned"). The pool does not hold that connection, so a true answer changes nothing there; core's listen machinery heals a dead listen connection on its own.
_idle_connection_alive
sub _idle_connection_alive {
my ($self, $conn) = @_;
... # local state, or what the server already sent -- no round trip
return $alive;
}
Driver seam: is the server session behind the idle pool connection $conn still there? Core's pool asks it each time "acquire" in DBIO::Storage::PoolBase is about to hand out an idle connection -- on every borrow of one, before the caller's first statement is sent -- through "_idle_connection_alive" in DBIO::Async::Pool, which delegates here. Same name, same contract as core's "_idle_connection_alive" in DBIO::Storage::PoolBase: this is where a future_io driver answers it, since it writes a storage adapter and never a pool of its own.
A false answer, or a throw, has the pool retire $conn -- closed once through _shutdown_pool_connection, no longer counted against the pool size, never handed out -- and try the next idle connection, then spawn a fresh one, or queue the caller when the pool is full. A throw also goes to the pool's on_error, so a broken check is not silent; core catches it, the pool passes it through untouched. Not asked about a connection the pool has just spawned, nor about one released straight to a caller queued for it: neither sat idle.
The default answers true without looking: no check, no cost, and an idle connection is handed out as it was before the seam. Fill it only if the driver can answer without a round trip -- from the handle's local state, or from a non-blocking read of what the server has already sent. It runs inside acquire on every borrow of an idle connection, so it must never block and never send anything to the server: no ping, no SELECT 1.
It is the borrow-time sibling of "_conn_error_is_fatal". That one reports a dead connection after a query on it failed; this one narrows the window before a query is sent on a connection that died while it sat idle -- a server restart, an idle timeout, an administrator's kill. Without it such a connection costs one caller a failed query first, and after a server restart one caller per idle connection. Neither closes the window alone: a connection can still die between this check and its first statement, or without the server saying so (a network partition); that statement fails, and "_conn_error_is_fatal" reports it as before. A driver filling one will usually fill both, from the same state.
What a driver can read, for example: whether its client library has already given up the socket -- for DBD::Pg, pg_socket below zero, the state a PostgreSQL driver reads for "_conn_error_is_fatal" too. And whether the socket is readable, by a check with a zero timeout: an idle connection has no query in flight, so a readable socket means the server sent something unasked -- which is what a server does when it ends an idle session (an error message, then end of file). Whether readable means dead depends on the engine. A MySQL server writes to an idle connection only as it closes it; a PostgreSQL server may also send a live idle session a notice, a parameter status or a notification, so there the driver has to let its client library consume what arrived, without blocking, and then look at the handle's state again.
This base makes the same zero-timeout readability check for its own listen watch loop (see "THE LISTEN WATCH LOOP"), as a private step of that loop. It does not offer it as a helper for this seam: what a readable idle socket means is the driver's to decide, and a helper would be shaped before a driver has used it.
_listen_drain
my $notifications = $storage->_listen_drain($conn);
# [ [ $channel, $payload, $sender_pid ], ... ] -- or a Future of that
Driver seam of the listen watch loop (see "THE LISTEN WATCH LOOP"): take every notification pending on the listen connection $conn and return them as an arrayref of [$channel, $payload, $sender_pid] tuples, in arrival order; an empty arrayref when nothing is pending. $payload and $sender_pid may be undef. The loop hands each tuple to "_listen_dispatch" in DBIO::Storage::Async in that order.
It may instead return a Future resolving to such an arrayref. An emulating transport must, since draining a notify table is a query, and on this transport a query is a Future -- run it on the listen connection with $self->_query_async_pinned($conn, $sql, \@bind). The loop holds that Future until it resolves and cancels it on "_listen_unwatch".
It dies, or its Future fails, when the connection is dead; the loop reports that to core through "_listen_lost" in DBIO::Storage::Async. In socket mode that includes end of file: the loop drains only when the socket is readable, and a readable socket that yields no data because the server closed it must die here -- a drain that answers [] instead leaves the loop polling a closed socket that stays readable, spinning hot and never healing.
In socket mode it is also called once right after the watch starts, whether or not the socket is readable, to pick up what the client library buffered during the subscribe round trip. It must therefore never block: read what is there and return.
_notify_sql
my ($sql, $bind) = $storage->_notify_sql($channel, $payload);
Driver seam of "_notify_send": the statement that sends one notification, as SQL in the sql_maker ?-placeholder dialect plus an arrayref of bind values -- "_query_async" shapes the placeholders. The payload travels only in $bind, never in $sql (ADR 0017 §3, restated by core ADR 0056); bind the channel too wherever the engine allows it. $payload may be undef.
SEAM HOOKS
Overridden by a concrete DBD subclass; each croaks until provided.
Query execution / connection lifecycle
"_submit_query" -- send query bytes to the wire (non-blocking)
"_collect_result" -- read the result from the wire
"_conn_ready" -- is the connection ready for queries?
"_conn_fileno" -- socket fd for the Future::IO watcher seam
"_create_pool_connection" / "_shutdown_pool_connection" -- pool connection lifecycle
Two more seams belong here, optional: until a driver fills them, their defaults leave everything as it was -- the pool is never told a connection died.
"_conn_error_is_fatal" -- did a failed query take its connection with it? A true answer has the pool retire the connection instead of handing it out again
"_idle_connection_alive" -- is an idle connection's session still there? Asked before the pool hands it out; a false answer has the pool retire it and take the next idle connection or a fresh one
SQL / connect-info shaping
The SQL-shaping seams (sql_maker_class, _transform_sql, _post_insert_sql) and the pipeline seams (_pipeline_enter/_pipeline_sync/_pipeline_exit) are inherited as croaking seams from DBIO::Storage::Async. This transport additionally requires:
"_normalize_conninfo" -- DB-specific connect-info conversion
The transaction-context seams are not among them: "_txn_context_class" and "_txn_conn_accessor" answer with this transport's own defaults, so an adapter names them only when it needs a different context class or constructor key.
LISTEN / NOTIFY
Core DBIO::Storage::Async owns the LISTEN/NOTIFY contract and its machinery -- registry, dedicated listen connection, serialised channel operations, self-healing, fork guard (core ADR 0056). Of its listen seams, the ones that are the same for every Future::IO transport are implemented here, once (ADR 0005): the backoff timer "_listen_delay", the watch loop "_listen_watch" / "_listen_unwatch" (see "THE LISTEN WATCH LOOP") and the pooled "_notify_send". A driver offering LISTEN/NOTIFY supplies the rest:
"_listen_drain" -- the notifications pending on the listen connection, in arrival order
"_notify_sql" -- the SQL and bind values that send one notification
_listen_open,_listen_close,_listen_subscribe,_listen_unsubscribe,_listen_probe-- inherited as croaking seams from DBIO::Storage::Async (see "Listen seams" in DBIO::Storage::Async)optionally "_listen_poll_interval" -- the watch mode: socket-driven by default, timer-driven when it answers a number of seconds
It then declares listen and notify in its own "transport_capabilities". This base declares neither: it cannot drain anything.
THE PINNED STATEMENT QUEUE
A connection runs one statement at a time, and this transport's own cycle has room for exactly one: "_submit_query" leaves the statement on the connection, "_collect_result" reads the result off it. A pooled connection is safe by construction -- between acquire and release it has one borrower, whose "_query_async" holds it for exactly one statement. A pinned one is not: a transaction context hands its connection to every statement the block issues, and a block that does not await one statement before issuing the next put the second on the wire while the first still ran. DBD::Pg then cleared the first statement's handle, the first never resolved, and the transaction's COMMIT -- which waits for every statement of the context -- waited forever.
So "_query_async_pinned" queues statements per connection, as the ev transports do: a statement is dispatched only once the one before it on that connection has settled -- done or failed. The caller gets a Future at once, and statements go out in the order they were issued. A statement that was waiting goes out once the caller's callbacks of the one before it have run: one those callbacks issue queues behind it, and one they cancel is never sent. A statement on an idle connection goes out at once, as before. This covers everything pinned: a transaction context, a pipeline context, core's BEGIN/COMMIT/ROLLBACK, an emulated "_listen_drain".
A connection is idle as soon as its statement has settled with nothing waiting behind it -- before that statement's callbacks run, so a statement they issue goes out at once, a synchronous one ($ctx->select, which is select_async(...)->get) included. That is the everyday case: core runs a transaction's block from the callback of BEGIN's Future, so every synchronous statement of a txn_do block is issued from inside one. Were the connection still counted busy there, the statement would wait for a queue that advances only once the block has returned, while its ->get waits for the statement -- nothing on the wire, the built-in Future::IO implementation dies (Cowardly refusing to sit idle), any other loop hangs. The queue is not all such a statement depends on, though: on Future::IO::Impl::IOAsync it goes out and then dies in its ->get, of that implementation's own read handler -- see "FUTURE::IO IMPLEMENTATIONS".
One case still cannot complete: a synchronous statement issued from a callback while statements issued before it still wait. Issue order puts it behind them, and they go out only once that callback has returned. Chain it (->then) instead of blocking, or await the waiting statements first.
How the queue treats what goes wrong:
A statement fails. The queue advances: the next statement is dispatched as it would have been had its caller chained it. A transaction fails with the first failure anyway.
A statement fails and the driver says its connection died ("_conn_error_is_fatal"). The statements that were already waiting behind it -- issued before anyone knew -- are failed without being sent: they would only go onto a dead handle. So is every statement issued afterwards, from the failed statement's callbacks or later: it fails with
not sent: this connection was reported dead ...and never reaches the driver -- core'sROLLBACKis one, and the transaction's error names it. The queue asks the pool (_connection_is_dead) at the one place it dispatches, so a refused statement is no query for "_conn_error_is_fatal" to classify a second time. Same rule as after a cancel in flight: nothing more is sent.A waiting statement's Future is cancelled. It is skipped and never sent; its SQL and bind values are dropped at the cancel.
The statement in flight is cancelled. Its Future::IO poll is dropped, as before, but its result is still on its way, and the base can neither read it nor cancel it on the server. Nothing more is sent on that connection: the statements waiting behind it and every later one fail without being sent, and the connection is reported dead to the pool ("_mark_connection_dead" in DBIO::Storage::PoolBase), so its hand-back retires it instead of passing the unread result to the next borrower. In a transaction that makes the
ROLLBACKfail, and the transaction fails saying so; the server ends the transaction when the retired connection is closed. A pooled query cancelled in flight retires its connection the same way ("_query_async").The connection is closed -- the storage disconnected, its pool shut down, the connection retired. A statement in flight fails saying so, and the queue refuses as it does after a cancel, with a reason of its own: the statements waiting fail without being sent, in the order they were issued, and so does every later one. An idle connection, which carries no queue, is given one at the close that only refuses. Nothing is reported to the pool, which closed the connection itself ("STATEMENTS IN FLIGHT").
The queue lives on the connection hashref under the reserved key _dbio_async_queue, next to _dbio_async_poll_fh ("_conn_poll_fh"): the statement in flight and the ones waiting. It is removed as soon as the connection falls idle, so a connection goes back to the pool without it; only a connection a cancelled statement left behind, or one the pool closed, keeps it, to refuse what comes next -- the first is retired, the second is closed already. A connection that is not a hashref gets no queue: its statements are dispatched at once, as before, and a driver with such a connection serialises them itself. They are held for the flight like any other ("STATEMENTS IN FLIGHT").
The number of statements waiting on one connection can be bounded with the connect option max_pending_pinned, and the time one statement may take on the wire with statement_timeout ("TIMEOUTS AND LIMITS").
A waiting statement holds its SQL and bind values until it is dispatched -- it cannot do otherwise -- and nothing holds them afterwards: the queue drops them as the statement goes out, and every callback it builds is made by a named sub that closes over the connection and Futures only (ADR 0044).
The queue serialises; it does not batch. A transport that pipelines on this base -- neither future_io adapter does; pipeline() refuses without "_pipeline_enter" in DBIO::Storage::Async -- has to put several statements on one connection before the first is answered, which this cycle cannot do anyway, and dispatches its batched statements through a "_query_async_pinned" of its own.
STATEMENTS IN FLIGHT
A statement on the wire -- a flight -- is this transport's: a Future::IO poll on the connection's socket, with the collect chained onto it. Future holds a Future derived with then only weakly, so such a chain lives exactly as long as somebody holds its end. That somebody is the storage (ADR 0007): every statement "_query_async" and "_query_async_pinned" put on the wire is entered into a register on the storage as it is dispatched, with its connection and the pool it was dispatched with, and taken out when its Future settles. The caller gets a Future of its own, settled from the flight's, never the flight itself. Two things follow.
A Future the caller lets go of is carried through. Fire-and-forget -- a create_async in void context, a notification nobody waits for -- no longer takes the chain with it: the answer is collected, a failure asks "_conn_error_is_fatal" as every failure does, and a pooled connection is handed back exactly once, or retired. Nothing announces the failure of a statement nobody waits for. The same holds one step earlier: a pooled query whose caller lets go of it while it still waits for the pool is dispatched when its turn comes. Before this, the poll resolved into nothing (Future warns lost a sequence Future), the result stayed unread and the connection checked out -- in a pool of one, for good.
Cancelling is not letting go, and does what it did: the caller's cancel reaches the flight, and a flight cancelled on the wire retires its connection.
A connection closed under its statement ends the flight. The pool closes a connection at its shutdown -- which is what "disconnect" in DBIO::Storage::Async runs, and DESTROY -- and when it retires one. For every connection it closes, "_shutdown_connection" in DBIO::Async::Pool first calls "_abandon_flights_on", and a statement in flight on it ends there:
its caller's Future fails, at the close, saying the connection was closed under the statement and that whether it took effect is unknown -- it may have reached the server;
the poll is let go of ("_let_go"): the loop watches the connection's socket no longer -- at once on the built-in Future::IO implementation, with the next event on that socket on Future::IO::Impl::IOAsync ("FUTURE::IO IMPLEMENTATIONS") -- nothing is read off the closed connection, and an answer that still arrives changes nothing;
on a pinned connection, the statements waiting behind it ("THE PINNED STATEMENT QUEUE") fail without being sent -- the rule for a statement cancelled in flight, with a reason of its own;
a callback on the caller's Future that dies there does not stop the teardown: the flight is still let go of, the connection still closed, and the death goes to the pool's
on_error.
Before this the Future stayed pending and the loop went on watching the dup of a socket whose connection was closed; a late answer ran "_collect_result" on that connection.
Where the pool closes nothing, nothing is ended. A forked child that tears down the storage it inherited closes none of the parent's connections ("_verify_pid" in DBIO::Storage::PoolBase), so it settles none of the parent's statements, and none of the parent's callbacks runs there. Nor does a child whose own loop turns do anything with a flight it inherited: a poll made in another process continues into nothing ("_await_readable"), so the child never collects, and the parent's answer stays on the socket for the parent. The inherited flights stay in the child's copy of the register, inert. In global destruction nothing is settled either, as core's pool settles none of its own Futures there. And a storage that is merely dropped with a statement in flight is not torn down under it: the flight holds the storage, completes, and the storage is freed after it.
A connection the pool closed gets nothing more sent, whether or not a statement was on it. A closed connection is finished: what is issued on it afterwards -- the next statement of a transaction that was between two statements at the teardown, core's ROLLBACK for it, anything a holder still sends -- fails saying the connection was closed, and never reaches "_submit_query". The transport refuses rather than the driver, because not every client library refuses a handle it closed: one that took the statement would leave a poll on a dead socket and a Future that never settles. With no statement in flight nothing fails at the close; the holder learns of it from its next statement. The mark is the pinned statement queue's, on the connection hashref; a connection that is no hashref has no place for it, and there the driver's handle is what refuses. A connection handed back to the pool open never carries it.
No completion builds a pool. What a settled statement has to tell a pool -- that its connection died, was abandoned, or comes back -- it tells the pool it was dispatched with: the one "_query_async" acquired from, and for a pinned statement the pool the storage had when the statement went out, if it had one. "pool" builds lazily, which is for a dispatch to trigger; asked from a completion it put a new, empty pool on a storage that had just been disconnected. With no pool there is nobody to tell, and that is not an error.
TIMEOUTS AND LIMITS
A statement, a wait and a queue each have a bound, set as connect options (core's async_option, "ASYNC OPTIONS" in DBIO::Storage::Async), for example
MyApp::Schema->connect($dsn, $user, $pass, {
async => 'future_io',
statement_timeout => 30,
max_pending_pinned => 100,
acquire_timeout => 10,
});
Every option left out is off, except acquire_timeout, which is 30 seconds in core. A value that does not fit the option's form is refused when the connect info is set; the message names the option and the form it takes, never the value.
statement_timeout-- seconds a statement may take on the wire, a number of seconds,0or more;0turns it off. The time runs from the moment the statement is sent to the server until its answer is read. When it is up, the statement is cancelled like any statement cancelled in flight ("_query_async", "THE PINNED STATEMENT QUEUE"): the poll is let go of and its connection is reported dead to the pool, which retires it, so the next borrower gets a fresh connection. The caller's Future fails withstatement timed out after N seconds (statement_timeout)-- the option and the seconds, never the SQL or the bind values -- and whether the statement took effect on the server is unknown. It applies to pooled and pinned statements alike. A pinned statement waiting in the queue is not on the wire and its time has not started; the statements waiting behind a statement that timed out fail unsent, as they do behind any cancelled one. The timer is the transport's "_delay" in DBIO::Storage::Async, here "_listen_delay" over Future::IO; it stops when the statement settles. Where the owning storage cannot make a timer, the statement runs without a time limit and the pool'son_erroris told.max_pending_pinned-- the number of statements that may wait for the statement in flight on one pinned connection, a positive integer. A statement issued when that many already wait fails at once, without being queued:not sent: ... max_pending_pinned, naming the option and the number, never the SQL or the bind values. The statements already waiting, and their order, are as they were. A connection that is not a hashref has no queue and no limit here.acquire_timeout,max_waiters,txn_timeout,reset_timeout-- the core's options, read by core: how long and how many callers may wait for a pool connection (the pool takes them from this storage, "new" in DBIO::Async::Pool), how long atxn_do_asyncmay take and how long the reset of a released connection may take. Their forms and defaults are in "ASYNC OPTIONS" in DBIO::Storage::Async and "new" in DBIO::Storage::PoolBase. Their timer is the same "_delay" in DBIO::Storage::Async.
TRACE
The transport carries no trace of its own. "_query_async" and "_query_async_pinned" hand each statement to "_debug_query" in DBIO::Storage::Async -- the SQL, the bind values and the optional $bind_attrs -- and run the coderef it returns, which calls query_end, when the statement has settled: done, failed or cancelled. What is traced at which DBIO_TRACE level, how the redact_bind_value hook is asked and where the output goes is that method's rule (ADR 0009, core ADR 0025). A statement without attributes -- BEGIN, COMMIT, a ping, a reset, _notify_send -- gives the hook undef for column name and attributes.
WINDOWS
The transport cannot wait on the socket of a DBD on Windows. The built-in Future::IO implementation waits with select, and on Windows select waits for sockets only, named by a Perl file descriptor. A DBD reports something else there: the socket of a database handle (DBD::Pg's pg_socket, for one) is a Winsock handle, not a Perl file descriptor. "_conn_poll_fh" turns the value of "_conn_fileno" into a filehandle with a dup of that file descriptor, and a Winsock handle is none -- the dup fails or lands on another descriptor. This dist converts nothing, so a driver whose "_conn_fileno" hands back such a handle gets no working transport on Windows, with the built-in implementation or with any other that takes a file descriptor. A driver's live tests should skip Windows, with this as the reason.
What does hold on Windows is the transport itself over a channel that is a socket with a Perl file descriptor: this dist's own test suite runs there on a socketpair (a loopback pair on Windows), apart from the tests of a forked child, which need fork and skip.
FUTURE::IO IMPLEMENTATIONS
Every wait this transport starts is a Future::IO poll on the dup of a connection's socket ("_await_readable"), and every one it gives up is a cancel of that poll ("_let_go"). What becomes of a poll in between is the implementation's, and some of what the two implementations this dist is tested on do with one reaches a caller. What follows describes Future::IO 0.23 and Future::IO::Impl::IOAsync 0.805, the newest releases when it was written. The transport does nothing about any of it. The three behaviours that keep a caller from what it is owed are held as they stand, as TODO on what is owed, by t/33-future-io-limits-builtin.t and t/34-future-io-limits-io-async.t. All three are defects of the implementations, reported upstream with patches and tests; with those applied, every one of these TODOs passes. The other implementations -- AnyEvent, Mojo, UV, Glib -- have not been looked at.
The built-in implementation
What Future::IO runs on when no Future::IO::Impl::* is loaded: no event loop, ->get on a Future turns a loop of its own. It is there for a script that has no event loop.
A poll cancelled from inside another poll's callback can kill the round. One round of that loop walks its list of polls with the list's length taken up front, and resolves the ready ones from inside the walk. A poll cancelled by a callback that runs there leaves the list at once. When it stood behind the poll being resolved, the walk runs off the end of the list and the round dies --
Can't call method "fh" on an undefined value at Future/IO.pm line 890-- out of whatever drove the loop: a->get, on a Future that is done by then.A statement in flight is a poll, the polls stand in the order the statements went out, and letting go of a statement is a cancel. So this is met by
Future->wait_anyover two pooled queries when the one issued first wins, since the loser is cancelled from the winner's callback; and by adisconnect, a pool shutdown or acancelmade in a query's callback while a statement issued after that query is in flight. The transport has done its part by then: the winner's rows are on its Future and its connection is back in the pool, the loser's connection is retired, a statement the teardown ended has failed saying so, and the loop is left with nothing stale on its list. What is lost is the return of that one->get. Catch its death and ask the Future again -- it is done, and hands out its result; or cancel, and tear down, outside of a callback; or run on an event loop's implementation.With read polls only, it does not wait for a socket. While it holds no timer, this implementation does not
select: it presumes every poll ready, resolves them in the order they were made, and clearsO_NONBLOCKon each handle while that poll's callbacks run. The driver's "_collect_result" then waits on its connection until the answer is there. So statements in flight at once on several pooled connections are answered one after the other, in the order they were issued, each waited for in turn -- not as their answers come in. Measured against a PostgreSQL server: apg_sleep(1.5)issued first and aSELECT 1issued second, raced withFuture->wait_any, are decided after 1.5 s, by the first; on IO::Async after 0.15 s, by the second. A timer pending in the loop --Future::IO->sleep, a listen backoff, a timer-driven listen watch -- makes itselectfor as long as that timer is pending. This is the implementation as it is meant to be, and the reason the listen watch loop confirms readability for itself ("THE LISTEN WATCH LOOP"). A program whose queries are to overlap runs on an event loop.
Future::IO::Impl::IOAsync
A cancelled poll keeps its watch. The implementation does nothing when a poll is cancelled: the loop goes on watching the handle, and holding it, until that handle next turns readable, and only then drops both. Here the handle is the dup of a connection's socket ("_conn_poll_fh"), and every statement let go of in flight leaves one behind -- a query cancelled in flight, a statement whose connection was closed under it, a listen watch that was stopped. The transport's part does not wait for it: the caller has its outcome at the cancel or at the close, the connection is retired or closed there, and an answer that still arrives is not read ("STATEMENTS IN FLIGHT"). What stays is the loop's watch and the dup's file descriptor, which holds the socket open on this side, until the next event on that socket: the abandoned statement's answer, or the server closing its end, as it does once the driver has closed the connection. There is nothing to do about it; a program that counts the loop's watches or its own file descriptors sees them go one event late.
A blocking call in a poll's callback dies when the socket turns readable again. The read handler resolves the first poll waiting on a handle and takes it off its list only afterwards. A callback that runs from that resolve and turns the loop itself -- a
->get-- while the same handle turns readable again has that event delivered to the poll that is already done, and the death comes out of its->get:IO::Async::Future=HASH(...) is already done and cannot be ->done at Future/IO/Impl/IOAsync.pm line 88.On this transport that is, first, a synchronous statement issued from the callback of a statement on the same connection: its own answer is the event. A pinned connection is always the same one; a pooled query's connection is back in the pool before its callbacks run ("_query_async"), so a synchronous query issued from one is handed that very connection whenever it is the idle one. And core runs a transaction's block from the callback of
BEGIN's Future ("THE PINNED STATEMENT QUEUE"), so every synchronous statement of atxn_doblock is such a statement:$ctx->select(...)in the block dies with the message above and the transaction is rolled back. Second, it is a channel callback oflistenthat blocks on anything while the next notification arrives on the listen socket; uncaught, core reports the callback's death through "on_listen_error" in DBIO::Storage::Async, and delivery goes on.In each case the statement was sent, and the transport still collects its answer and hands its connection back; what is lost is the caller's
->get, and with it a transaction whose block dies of it. On this implementation, chain the statements of a block instead of blocking on them --$ctx->select_async(...)->then(...)under "txn_do_async" in DBIO::Storage::Async commits -- and do not block in a callback. The built-in implementation runs the blocking form.
THE LISTEN WATCH LOOP
"_listen_watch" starts, and "_listen_unwatch" stops, one generic loop per listen connection. It has two modes, chosen by "_listen_poll_interval" when the watch starts:
socket-driven (the default,
undef) -- wait until the connection's socket is readable ("_await_readable", on the cached dup from "_conn_poll_fh"), drain, dispatch, wait again. The first drain runs one loop tick after the watch starts, before the first poll: a client library may already hold notifications it read off the socket during the subscribe round trip (libpq does), and those will never make the socket readable again. That first drain is deliberately not run inside "_listen_watch" itself. When the seams resolve synchronously, as a blocking DBI connect does, core calls "_listen_watch" from inside "listen" in DBIO::Storage::Async and "listen_reconnect" in DBIO::Storage::Async, and fires "on_listen_reconnect" in DBIO::Storage::Async only once it has returned. A drain inside it would run a channel callback before that call returned -- and only when something happened to be buffered -- and, on a rebuilt connection, before the hook that tells the consumer the stream broke.After every poll the loop confirms readability with a zero-timeout
selecton the dup before it drains, and simply polls again when the socket is quiet. Future::IO's built-in implementation does notselectat all while it has only read pollers and no timer: it presumes each poll ready and clearsO_NONBLOCKon the handle while the callback runs. A drain called then on a quiet socket would block inrecv-- and with it the query the program was actually waiting for -- until the next notification arrived.timer-driven (a positive number of seconds) -- wait that long ("_listen_delay"), drain, dispatch, wait again. For an engine with no server push, emulating notifications with a notify table: latency is the poll interval, and a notification becomes visible when the transaction that wrote it commits. A driver that declares
listenin this mode must state both in its POD (core ADR 0056 §6). In this mode the loop itself never touches the socket: it calls neither "_conn_fileno" nor "_conn_poll_fh" (a drain that runs its query through "_query_async_pinned" polls the socket for that query, as any query does).
Each tuple "_listen_drain" returns goes to $self->_listen_dispatch($channel, $payload, $sender_pid), in the order drained. Any error -- the poll or the timer failing, the drain dying or its Future failing, a malformed drain result, a throw anywhere in the iteration -- goes to $self->_listen_lost($conn, $error) and ends the loop; core heals by opening a new connection and watching that.
The loop keeps its state on the connection hashref under the reserved key _dbio_async_listen_watch (next to _dbio_async_poll_fh, see "_conn_poll_fh"): the watching process's pid, the mode, and the Future the loop currently awaits. The callbacks the loop registers hold the storage, the connection and that state only weakly, so the one strong path is connection -> state -> pending Future and nothing points back. The state also holds a driver's pending drain Future strongly -- nothing else may: a Future holds the Futures derived from it only weakly.
The state is the watch's identity. Every iteration checks, before each dispatch and before re-arming, that it is still the state on the connection; "_listen_unwatch" removes it. So a channel callback that unlistens the last channel, or calls listen_reconnect, in the middle of a batch ends the loop right there: the rest of that batch is not dispatched and nothing is re-armed. The recorded pid does the same across fork: a poll inherited by a child whose own loop fires it does nothing, so the child never reads the parent's socket.
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.