NAME
Fetch::Future - a fast, native, Future-compatible async result
SYNOPSIS
my $f = Fetch::Future->new;
$f->on_done(sub { my $v = shift; ... });
$f->done(42);
my $all = Fetch::Future->needs_all($f1, $f2);
my @v = $f->get; # pumps the active loop (or Standalone) until readyDESCRIPTION
An asynchronous result with an API compatible with CPAN Future: done/fail/cancel, on_ready/on_done/on_fail, then/else/followed_by/transform, get/await, and the convergent combinators wait_all/wait_any/needs_all/needs_any.
The implementation is entirely XS over an array-slot object; continuations are C closures trampolined through a fire queue, so long then-chains run iteratively with bounded stack depth.
get/await on a pending future pump the current event loop re-entrantly. Outside a running loop, an external loop may install $Fetch::Future::AWAIT (a coderef receiving the future) to make awaiting work.
as_cpan_future / from_future convert to and from CPAN Future objects for interop with isa('Future') code.
CONSTRUCTORS
new
my $f = Fetch::Future->new;A new pending future.
done_future(@values) / fail_future(@failure)
my $f = Fetch::Future->done_future(42);
my $f = Fetch::Future->fail_future("nope\n");An already-resolved future, done with @values or failed with @failure.
RESOLVING
done(@values)
Mark a pending future done with @values; fires its ready/done callbacks. Returns the future.
fail($message, @details)
Mark a pending future failed. Returns the future.
cancel
Cancel a pending future.
STATE
is_ready / is_done / is_failed / is_cancelled
Booleans: whether the future has settled at all, and how.
CALLBACKS
on_ready($cb)
Call $cb->($future) when the future settles (done, failed or cancelled). Returns the future.
on_done($cb) / on_fail($cb)
Call $cb->(@values) on success, or $cb->(@failure) on failure. Return the future.
CHAINING
Each returns a new future and flattens a future returned by the callback, so long chains compose without nesting.
then($on_done) / then($on_done, $on_fail)
Run $on_done with the values when this future succeeds; its result (a value list or a future) becomes the new future's result. Failure passes through unless $on_fail is given.
else($on_fail)
Like then but for the failure branch.
followed_by($cb)
Call $cb->($future) once this future settles either way, and adopt the future it returns.
transform(done => $cb, fail => $cb)
Map the done values and/or failure through the given coderefs.
AWAITING
get / result
my @values = $f->get; # or a scalar in scalar contextBlock until the future is ready, pumping the active event loop (the Standalone loop if none), then return its values - or rethrow its failure.
await
Block until ready (pumping the loop) and return the future itself.
failure
The failure of a failed future (the first failure value), or undef.
COMBINATORS
Each takes a list of futures and returns one future.
needs_all(@futures)
Done when all succeed (with their combined values); fails as soon as any fails.
needs_any(@futures)
Done as soon as any succeeds; fails only if all fail.
wait_all(@futures)
Done when all have settled, whatever the outcome.
wait_any(@futures)
Done as soon as any has settled.
INTEROP
as_cpan_future
A real CPAN Future that settles when this one does, for code expecting isa('Future').
from_future($cpan_future)
my $f = Fetch::Future->from_future($cpan_future);A Fetch::Future that mirrors the given CPAN Future.
AUTHOR
LNATION <email@lnation.org>
LICENSE AND COPYRIGHT
This software is Copyright (c) 2026 by LNATION. This is free software, licensed under the Artistic License 2.0.