NAME

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

VERSION

version 0.900007

DESCRIPTION

The Future class of DBIO::MySQL::EV::Storage (its "future_class" in DBIO::MySQL::EV::Storage). Every Future this transport hands out is settled from the EV loop -- by an idle watcher that follows the EV::MariaDB callback of its statement, or by an EV timer -- 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). It works inside a callback of one of the transport's own connections too -- a then on its Futures, the coderef of txn_do: those run from the idle watcher, outside every callback of the EV::MariaDB handle (ADR 0001 addendum). What it still refuses is a wait for a pooled connection that cannot come back while the callbacks it runs inside hold every one of them ("await").

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 waits inside a callback of the transport's own connections. A then or on_done on its Futures and the coderef of txn_do / txn_do_async run from the idle watcher that settles the Future ("execute" in DBIO::MySQL::EV::QueryExecutor), not from inside the EV::MariaDB callback that delivered the answer, so the handle's callback depth is 0 there and a statement they send -- with or without bind values -- is sent at once. A blocking call waiting for it returns. (EV::MariaDB only queues a query issued while a callback of its handle runs and sends it when that callback returns; the transport's Futures settle outside it.) The nested loop serves every watcher, the idle watcher included, so the statements of other connections settle meanwhile and their callbacks run in the order the handles answered.

It refuses a wait for a pooled connection that cannot come back while the wait lasts (ADR 0001 addendum). A blocking call on the storage takes a connection from the pool, and is queued when every one is checked out. Made inside a txn_do coderef -- $storage->select where $ctx->select_async was meant -- it needs another connection than the transaction's, and the transaction gives its own back only after the coderef has returned and COMMIT or ROLLBACK has been answered. With a pool of one, or with every connection held by a transaction this call is nested in, the queued call is never served.

await therefore asks, on entry and around 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 a callback that is running: a callback of its own on the call stack, and no statement in flight ("_mysql_held_by_callbacks" in DBIO::MySQL::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 and what to do instead: the transaction context's *_async methods chained with then, to run on the transaction's connection; the storage's *_async methods chained with then, for a statement that belongs outside it; or a larger pool_size. The failure reaches the waiting Future through its chain, so get dies with it.

The other wait that dies rather than ends -- the loop that has run dry with nothing left to settle the Future -- takes such a queued caller out of the queue as well, and fails it, before it dies. It would otherwise stay queued: the next release would hand its connection to a caller nobody waits for, and the pool would lose that connection.

  • The refused call does not run, then or later. It never had a connection; taken out of the queue, it gets none. A refused insert writes nothing. 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. A connection whose callback is running but that still has a statement in flight keeps the wait going; the wait is refused when that statement has been answered and nothing else gives a connection back.

  • 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 coderef -- stays queued and runs once the transaction has ended.

  • 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.

  • A transaction whose coderef has returned a Future that itself depends on a call queued for the transaction's connection -- txn_do(sub { $storage->select_async(...) }) with a pool of one -- is not a blocking wait inside a callback, and is not detected: the transaction waits for the call and the call for the transaction's connection.

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; a Future that nothing is going to settle while, say, a listen poll timer runs therefore waits as long as that timer does, like an IO::Async::Future would.

new

$f = DBIO::MySQL::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::MySQL::EV::Pool calls it on the Future it hands to "acquire" in DBIO::Storage::PoolBase. Returns the Future.

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.