NAME
DBIO::Async::Future - The Future a caller waits on for a pool connection, blocking via Future::IO
VERSION
version 0.900007
DESCRIPTION
The waiter DBIO::Async::Pool queues when a caller has to wait for a connection ("_new_waiter" in DBIO::Async::Pool). It is a plain Future in every respect but two:
Blocking drives the loop. Every
->thenoff a pending Future is made with that Future's ownnew, so the whole chain a caller builds on the wait -- the Futureacquirereturns, the query chained off it, the Future a sync storage method finally->gets (ADR 0001) -- is of this class. A plain Future knows no event loop and croaks is not yet complete and does not provide ->await on agetwhile pending. Here "await" drives Future::IO instead: on whichever implementation is loaded, the built-in one or aFuture::IO::Impl::*, with no event loop required.A blocking wait that dies takes its waiter back. When the loop cannot go on -- the built-in implementation dies with Cowardly refusing to sit idle and do nothing when nothing is on it, which is the sync call made inside a transaction block of a pool of one, whose holder is the caller itself -- the waiter is withdrawn from the pool's queue ("_withdraw_waiter" in DBIO::Storage::PoolBase) and failed with the error, and the error goes on to the caller. Left queued, the next release would hand the connection to a waiter nobody reads, and the pool would be wedged.
Callers that stay asynchronous see a Future like any other; nothing here is involved unless get or await is called on a pending one. What an implementation does with the poll that await makes is its own (the built-in one dies on a loop with nothing on it; under a real loop the same case hangs, as the loop is never asked to stop) -- see "FUTURE::IO IMPLEMENTATIONS" in DBIO::Async::Storage.
METHODS
new
my $waiter = DBIO::Async::Future->new;
my $derived = $waiter->new;
As a class method, a plain pending Future. On an instance, a new one that carries the instance's pool mark along ("mark_pool_wait"), the way IO::Async::Future carries its loop: every Future derived with then from a pool wait knows the wait it hangs off.
mark_pool_wait
$waiter->mark_pool_wait($pool);
Records on the waiter, and so on everything derived from it, the pool that queued it. The pool and the waiter are held weakly: the pool holds the waiter in its queue, and a Future derived from it must not keep either alive. Returns the waiter.
await
$future->await;
Blocks until the Future is ready, running Future::IO -- one made-up pending Future of the loaded implementation's own class (cloned from a sleep, so the await is the implementation's) that is resolved when this one settles, awaited. Does not throw on a failed Future, as await in Future does not.
If the implementation dies while it waits, the waiter this Future hangs off is withdrawn from its pool and failed, if it is still queued, and the error is rethrown (see "DESCRIPTION").
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.