NAME

DBIx::Loop::Future - the canonical future for DBIx::Loop

DESCRIPTION

A minimal, one-shot future. The hot primitives (new, done, fail, on_ready, is_ready, is_done, is_failed, failure, get) are implemented in C, and so are then and else: a continuation is an array on the future's own callback queue rather than a compiled closure, so settling a chain runs no Perl frame except your own callbacks.

This is the future DBIx::Loop returns on loops that have no native future (AnyEvent, POE). On loops that do (IO::Async Future, Mojo Mojo::Promise, Hyperman hmf), the loop adapter's future factory returns that native type instead. See DBIx::Loop.

get returns the result only once the future is ready; awaiting a pending future is the event loop's job, not the future's.

ASYNC/AWAIT

This class implements the Future::AsyncAwait::Awaitable API, so one of these can be awaited directly:

use Future::AsyncAwait;

async sub row_count {
    my @rows = await $db->query('SELECT * FROM things');
    return scalar @rows;
}

Whatever it awaited, an async sub returns a CPAN Future by default. Naming this class at import makes it return one of these instead:

use Future::AsyncAwait future_class => 'DBIx::Loop::Future';

Two limits follow from what this future is, and both are deliberate:

-

It cannot be cancelled. A DBIx::Loop::Future settles exactly once, into done or failed, and has no cancel. Cancelling the future an async sub returned, or abandoning one part way, is not available.

-

A toplevel await does not block. There is no blocking wait here to run, so awaiting a pending future outside an async sub reports that it is not ready rather than waiting for it. Run your event loop.

Which class you get depends on the loop, so whether await works at all does too. See "Futures and the loop you are on" in DBIx::Loop.

AUTHOR

LNATION <email@lnation.org>