NAME

DBIO::PostgreSQL::EV::Future - A Future whose get waits on the EV loop

VERSION

version 0.900007

DESCRIPTION

The Future class of DBIO::PostgreSQL::EV::Storage (its "future_class" in DBIO::PostgreSQL::EV::Storage). Every Future this transport hands out is settled from the EV loop, by an EV::Pg callback, so waiting for one means running that loop. A plain Future cannot: its get on a pending instance calls await, which Future leaves to subclasses and by default dies with "... is not yet complete and does not provide ->await". This class supplies it, the pattern of IO::Async::Future and the Future::IO implementations.

It is what makes the blocking storage methods work -- select, insert, txn_do, deploy, ..., each $self->X_async(@_)->get -- and it makes get on any other Future of this transport block the same way (ADR 0001). Inside a callback of one of the transport's own connections it dies instead ("await") where the wait could not end: when it would make EV::Pg hand a result to the wrong callback and spin, and when it is queued for a pooled connection while the callbacks it runs inside hold every one of them. The second it refuses as well inside a connection's opening -- in the AccessBroker's answer, or in a callback the loop ran while the pool waited for it or for a connect statement.

Nothing else changes. Everything but "await" and "new" is Future's own, and its combinators keep the class: then and friends on a pending instance, and needs_all / wait_any and the other convergents over instances of this class, return instances of this class.

METHODS

await

$f = $f->await;

Runs the EV loop one iteration at a time (EV::run(EV::RUN_ONCE)) until the Future is ready, then returns it; "get" in Future calls it for a pending Future.

It may be called from inside an EV callback: libev runs loops recursively, so the nested run serves every watcher, the caller's own ones included, and returns to the callback once the Future is ready.

It refuses a wait that could never end inside a callback of one of this transport's own connections -- a then or on_done on its Futures, or the coderef of txn_do / txn_do_async, which runs inside the BEGIN's callback on the pinned connection. EV::Pg keeps the callback it is delivering to at the head of the connection's queue until that callback returns. A nested loop that reads the next result on the same connection therefore hands it to that callback a second time instead of to its own, shifts every later result onto the wrong callback, and then spins inside EV::Pg with 100% CPU -- no EV timer and no alarm fires there (EV::Pg 0.07; 0.09 no longer spins and misdelivers, but hands the nested loop nothing until the callback has returned, so the wait still never ends -- measured). The next result is due whenever more than the delivering statement is pending on that connection: a statement issued from the callback -- EV::Pg sends it at once, with or without bind values, so the failure is certain -- or the rest of a pipeline batch, where it depends on whether the server flushes the next result while the wait runs. While one of this transport's callbacks runs for a connection whose "pending_count" in EV::Pg is above one, await dies -- on entry, and again before every iteration of the loop, because such a statement may be issued while the wait runs -- with "Blocking wait refused: ...", pointing to the *_async methods. Chain with then there instead of blocking.

In a txn_do coderef this refuses every blocking $ctx method: each sends its statement on the pinned connection whose BEGIN callback is running. Use $ctx->select_async and its siblings.

What the refusal does and does not do:

  • It cancels nothing. The statement is already on the wire and completes once the callback has returned.

  • The refused operation still completes, when it is on the wire. Before it dies, await keeps the Future it was asked to wait for alive until that is ready ("retain" in Future): Future holds a sequence Future only weakly, so the chain the dying caller drops would otherwise lose its remaining steps -- the release of a pooled connection among them. A call that is still queued for a connection has no statement on the wire: it is taken out of the pool's queue and failed, and does not run (below).

  • A refused txn_do coderef rolls back cleanly. The coderef dies while its statement is still running on the pinned connection, and the pinned connection runs its statements one at a time, so the ROLLBACK core sends goes out once that statement has its result: txn_do fails with the refusal, and the connection goes back to the pool IDLE ("_query_async_pinned" in DBIO::PostgreSQL::EV::Storage).

  • It is over-strict in one window: while more results are due on the connection, every blocking wait is refused, also one that does not depend on them, and in a pipeline also one the server would have answered in time.

  • It only knows the callbacks DBIO::PostgreSQL::EV::Storage hands to EV::Pg to settle its Futures, which are the ones a then chain or a txn_do coderef runs in. The LISTEN / UNLISTEN on the dedicated listen connection are among them; the notifications it delivers and the pool's connect-action replay are not.

A blocking call waiting only on other connections completes, as does one made from a plain EV callback -- a timer, an AnyEvent or IO::Async handler running on EV. So does one inside a then on a pooled Future, as long as the pool can hand it another connection: the connection whose callback runs is still checked out then.

It refuses a wait for a pooled connection that cannot come back while the wait lasts (ADR 0001 amendment). A blocking call on the storage takes a connection from the pool, and is queued when none is idle and the pool has no room to open one: it is at its size, or what it has left is taken by a connection it is opening right now (below). Two callers hold a connection for as long as they run. A then or on_done on a pooled statement's Future: the statement's callback settles the Future first and hands the connection back after ("_dispatch_query" in DBIO::PostgreSQL::EV::Storage). And the coderef of a txn_do / txn_do_async: the transaction gives its connection back only once the coderef has returned and COMMIT or ROLLBACK has been answered. A blocking call on the storage made there -- $storage->select in a coderef where $ctx->select_async was meant -- needs another connection. With a pool of one, or with every connection held by a callback this call is nested in, it is queued for a connection its own caller holds. Nothing is sent, so nothing is due and the refusal above does not see it; and EV::Pg keeps the held connection's read watcher counted while the callback it delivers to runs, so the loop does not run dry either.

A connection that is being opened is held the same way. The pool opens a connection synchronously, inside the acquire that found room for it, and calls code on the way that is not its own: the AccessBroker asked for the connect info, and the replay of on_connect_do / on_connect_call, which runs the loop until the server has answered ("_run_pool_connect_statement" in DBIO::PostgreSQL::EV::Storage). The spawn holds its slot throughout ("acquire" in DBIO::Storage::PoolBase), so a call on the storage made from inside it -- by the broker itself, or by a callback the loop runs while the broker's client fetches or the replay waits, a timer of the application, say -- finds no room and is queued behind it, although the pool holds fewer connections than its size. The spawn is a frame below that call on the call stack: the connection is handed out only after it has returned, and a blocking wait for it cannot end. A wait that does not see this dies with "... the EV loop has nothing left that could complete it" when nothing else is on the loop; with a watcher that keeps the loop alive -- the storage's own LISTEN connection is one -- it hangs (measured against PostgreSQL, t/78-blocking-behind-spawn-live.t).

await therefore asks, on entry and before every iteration of the loop, whether the Future it waits for is chained off a caller queued for a connection ("new"), and whether every connection of that pool is held by something on the call stack: none idle, and each either with a callback of this transport on the call stack and nothing but that callback's statement pending, or being opened by a spawn that is running ("_pg_held_by_callbacks" in DBIO::PostgreSQL::EV::Pool). If so, it takes the caller out of the pool's queue and fails it with "Blocking wait refused: ...", naming the size of the pool, what holds its connections -- the callbacks this call runs inside, or how many of them the pool is opening in a call this one runs inside -- and what to do instead: the *_async methods chained with then; in a txn_do coderef the context's, to run on the transaction's connection; or a larger pool_size. The failure reaches the waiting Future through its chain, so get dies with it. An AccessBroker that makes the blocking call itself and lets the refusal through fails the call whose connection was being opened; the spawn then took no slot.

  • The refused call does not run, then or later -- unlike the refusal above, which cancels nothing. It never had a connection, and taken out of the queue it gets none: a refused insert writes nothing. Left queued it would be handed the connection once the callback has returned, and run after its caller was told it had failed. In a txn_do coderef the refusal fails the coderef, so the transaction is rolled back and its connection goes back to the pool.

  • A wait that can end is not refused: one for a connection that is idle or still connecting, that a statement in flight will give back, or that is held by a transaction none of whose callbacks is running -- and any wait at top level or in a plain EV callback, where no callback of a connection runs and no connection is being opened below it. A connection being opened is no reason by itself: with another one busy with a statement in flight, the call waits for that one and runs on it.

  • Only the caller that is waited for is failed. A call queued for the connection without anybody blocking on it -- an unawaited $storage->select_async in the callback -- stays queued and runs once the callback has returned.

  • Where both refusals apply, the first one speaks: a blocking call on the storage in a txn_do coderef that has a $ctx statement in flight is refused for the result that is due, with that refusal's text. The call is queued for the transaction's connection, has none yet, and is taken out of the queue and failed all the same: it does not run once the transaction has given its connection back. The statement of the $ctx that is on the wire completes. A convergent that holds the queued call beside a statement already on the wire fails with it, as Future has a convergent do.

  • It sees the queued caller through "new", that is, in a Future chained off it with then and its siblings, or in a convergent whose first component is. A blocking wait on a Future that reaches a queued caller another way -- a then callback that returned the Future of a storage call, on a Future that was pending before -- is not refused and waits as before.

  • It refuses only what the call stack makes certain. A connection held with none of its callbacks running counts as one that can come back, whoever holds it: a blocking call queued behind a transaction that waits for something that never happens still waits as long as that does.

  • A transaction whose coderef returns the Future of a call on the storage -- txn_do(sub { $storage->select_async(...) }) with a pool of one -- is no blocking wait for a queued caller: the transaction waits for the call and the call for the transaction's connection, and await is not involved. It is refused where core asks for the Future the coderef returned ("_txn_inner_future" in DBIO::Storage::Async): "_txn_inner_future" in DBIO::PostgreSQL::EV::Storage calls _refuse_queued on it, and when every connection of the pool is held by a callback on the call stack -- the BEGIN's callback running the coderef is one -- the call is taken out of the queue and failed with the refusal above. The coderef's Future fails, the transaction is rolled back, txn_do dies with the refusal and the connection goes back to the pool; the refused call never runs. A call on the storage that finds a connection idle (a pool of two) is no wait that cannot end: it runs on that connection, outside the transaction, and nothing is refused.

  • It knows the callbacks the refusal above knows, and no others: a connection counts as held by a callback only inside one DBIO::PostgreSQL::EV::Storage handed to EV::Pg. And of a connection being opened it knows the two stretches the pool and this transport run themselves ("_pg_opening" in DBIO::PostgreSQL::EV::Pool): whatever else runs the loop inside a spawn, not through the connect statement seam, is not seen, and a blocking call made in that loop waits as before.

  • It does not wait for what only something outside the call stack could do. A timer that shuts the pool down ($storage->disconnect) would fail the queued caller too; the wait is refused before it gets there.

It dies instead of spinning when the loop has nothing left that could settle the Future: an iteration after which no watcher that keeps the loop alive is active -- no statement in flight, no timer -- while the Future is still pending. Such a Future would never become ready (EV answers at once when there is nothing to wait for, so a plain until loop would burn a core forever). A watcher that is active does keep it waiting, as it should, like an IO::Async::Future would.

Whichever way a wait is given up on while the Future hangs off a caller that is still queued for a connection -- the refusal above, the one for more results due, or the loop running dry -- that caller is taken out of the pool's queue and failed, with the text of the refusal that was raised. Left queued, the next release would hand it the connection: it would run after its caller was told the wait had failed, or, its chain dropped with the dying caller, the connection would be lost and a pool of one wedged. A callback that dies as the queued caller is failed is warned about; the pool is in order before it runs.

new

$f = DBIO::PostgreSQL::EV::Future->new;
$f = $other->new;

"new" in Future. Called on an instance that waits for a caller queued for a pooled connection ("_queued_in"), the new Future waits for that caller too: this is how Future makes the Future of every then and its siblings on a pending instance, and the one a convergent (needs_all, ...) returns. So everything chained off a queued caller knows it -- the Future a blocking call finally waits on, which is what "await" looks at. A queued caller that has been served, or failed, is no longer carried along.

_queued_in

$waiter->_queued_in($pool);

Mark this pending Future as the one a caller queued for a connection of $pool waits on. "_new_waiter" in DBIO::PostgreSQL::EV::Pool calls it on the Future it hands to "acquire" in DBIO::Storage::PoolBase. Returns the Future.

_held_by_callback

my $held = DBIO::PostgreSQL::EV::Future->_held_by_callback($conn);

Class method. True while one of this transport's callbacks is being delivered for $conn and nothing but that callback's statement is pending on it ("pending_count" in EV::Pg at most one): the connection has nothing in flight the loop could answer, and whatever is to happen on it next -- the release of a pooled statement's connection, a transaction's COMMIT or ROLLBACK -- waits for that callback to return. False for a connection none of whose callbacks runs, whatever holds it, and for one with more pending: a result is due there, and "await" refuses a wait for that reason first. "_pg_held_by_callbacks" in DBIO::PostgreSQL::EV::Pool asks it of each of its connections.

_replaying

my $replaying = DBIO::PostgreSQL::EV::Future->_replaying($conn);

Class method. Marks $conn as a connection whose connect actions are being replayed, for as long as the returned frame lives. "_run_pool_connect_statement" in DBIO::PostgreSQL::EV::Storage keeps it in a lexical while it runs the EV loop for a connect statement: the pool counts the connection by then, it is not idle, and no callback of this transport is being delivered for it -- yet it is handed out only once the spawn that replays on it has returned, and whatever runs in that loop runs above the spawn on the call stack. "_held_by_spawn" answers from the mark.

_held_by_spawn

my $held = DBIO::PostgreSQL::EV::Future->_held_by_spawn($conn);

Class method. True while the connect actions of $conn are being replayed ("_replaying"): the spawn that opens it is running, and the connection cannot be handed out before that has returned. "_pg_held_by_callbacks" in DBIO::PostgreSQL::EV::Pool asks it of each of its connections, beside "_held_by_callback".

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.