NAME

DBIO::Forked::Future - Loop-free, pipe-backed Future for DBIO::Forked

VERSION

version 0.900007

DESCRIPTION

A loop-free Future implementation over a pipe read fd, with no Future, no Future::IO and no event loop. It is what DBIO::Forked::Storage hands back from its *_async methods.

It fulfils both the minimal core DBIO::Future contract (then / catch / get / is_ready / is_failed) AND the fuller, DBIO::Future::Immediate-compatible surface (the done / fail / needs_all class constructors, plus and_then), so it works as a live future_class for core's ResultSet async helpers (all_async / first_async / single_async / count_async / create_async), which build futures via $storage->future_class->done(@rows) and ->fail($err).

The model is deliberately simple, matching Model A (one forked child per query):

  • is_ready is an EOF-clean, non-blocking drain. IO::Select->can_read(0) goes true as soon as the child writes anything, not when it is done, so a bare peek would be premature. Instead is_ready reads whatever is available without blocking and accumulates it across calls; it returns true only once the child closes its write end (sysread returns 0 = EOF), at which point the blob is thawed, cached and the child reaped.

  • get blocks until EOF, Storable-thaws the accumulated blob, waitpid-reaps the child, and returns the rows -- or re-throws the child's error. It is idempotent: the result is cached, so a second get does not read or reap again.

  • then / catch / and_then compose lazily. A derived future stores its callbacks and a reference to its source; it resolves (running the callback synchronously, since the source is by then ready) the first time it is forced via get, or via is_ready/is_failed once the source is ready. No callback runs before its source has resolved, and nothing blocks unless get is called. A callback runs at most once: if it returns a future that is still pending, the derived future stays unresolved until that one resolves, and polling it in the meantime does not call the callback again.

  • done / fail / needs_all are immediate class constructors (no fork): a settled future is a pre-resolved leaf with no child, so it flows through the same resolution machinery. needs_all blocks on each input via get in turn (the children already run in parallel).

METHODS

new

my $future = DBIO::Forked::Future->new(read_fh => $fh, pid => $pid);
my $future = DBIO::Forked::Future->new(read_fh => $fh, pid => $pid, timeout => 5);

Construct a leaf future bound to the pipe read handle read_fh and the forked child pid, owned by the constructing process (see "PROCESS OWNERSHIP"). Both are optional so the object can be built before the fork wiring is in place.

timeout is a number of seconds above 0, counted from construction. A future still unresolved when it runs out is ended the way "cancel" does and fails with DBIO::Forked::Future: statement_timeout exceeded. The deadline is checked by whatever asks the future: "get" waits no longer than the time that is left, and "is_ready" / "is_failed" look at the clock before they report pending. A result that has arrived by then is taken as it is.

done

my $f = DBIO::Forked::Future->done(@values);

Class method: an immediately-resolved successful future carrying @values, with no fork and no pipe. This is the constructor core's ResultSet async helpers call as $storage->future_class->done(@rows).

fail

my $f = DBIO::Forked::Future->fail($error);

Class method: an immediately-resolved failed future; "get" re-throws $error. The ResultSet async helpers call $storage->future_class->fail($err).

needs_all

my $f = DBIO::Forked::Future->needs_all(@futures);

Class method: resolves once ALL @futures have resolved, collecting their values in order; fails as soon as any one fails, with that future's error. Under Model A the forked children already run in parallel; needs_all just blocks on each in turn via "get". Because collection is serial and each child holds its result in the pipe until read, a batch of many large results can stall on the pipe-buffer ceiling (see docs/adr/0003); fine for modest result sets.

then

my $g = $future->then(sub { my @result = @_; ... });

Success continuation. Returns a new DBIO::Forked::Future that, when forced, runs the callback with this future's resolved values and resolves to the callback's return values. On failure the callback is skipped and the failure propagates (unless an optional second $on_fail argument is given).

catch

my $g = $future->catch(sub { my $error = shift; ... });

Failure continuation. Returns a new DBIO::Forked::Future; on failure it runs the callback with the error and resolves to its return values, on success it passes the values through unchanged.

and_then

my $g = $future->and_then(sub { my @r = @_; return DBIO::Forked::Future->done(...) });

Like "then", but the callback is expected to return a future, which is flattened into the chain (no future-wrapping-a-future). Mirrors "and_then" in DBIO::Future::Immediate. (then already flattens a returned future, so and_then is then with future-returning intent made explicit.)

get

my @result = $future->get;

Block until resolved, then return the resolved values -- or croak with the child's error if it failed. Idempotent. Like "get" in DBIO::Future::Immediate, in scalar context it returns the first value (not the count).

is_ready

if ($future->is_ready) { ... }

Non-blocking. True once resolved (the child has finished and its blob been read, or the source of a derived future has resolved). Never blocks.

is_failed

if ($future->is_failed) { ... }

Non-blocking. True once resolved and the result is an error.

cancel

$future->cancel;

End the query. The child gets SIGTERM; if it is still there after one second it gets SIGKILL, and it is reaped either way. The future then fails with DBIO::Forked::Future: cancelled: "is_failed" is true and "get" croaks with that message. cancel on a future that has already resolved does nothing. On a derived future (then / catch / and_then) it cancels its source.

Only the process that created the future may cancel it; in any other process it fails with belongs to process N (see "PROCESS OWNERSHIP").

REAPING THE CHILD

Every child is reaped exactly once, by get/is_ready once the pipe hits EOF, or by the destructor of a Future that was never collected.

  • The destructor ends the child. A dropped Future whose query is still running ends its child the way "cancel" does (SIGTERM, then SIGKILL after one second) and reaps it, so letting a Future go out of scope never waits for the database. The destructor closes the read end first. The database decides what becomes of a statement whose client was ended; a transaction that had not committed is rolled back by the server.

  • $? is the caller's. Reaping localises $?, $! and (in the destructor) $@, so the exit code of a dying script and the status of the caller's last command survive. ${^CHILD_ERROR_NATIVE} is not so lucky: waitpid sets it to the child's status and it cannot be restored, so read it after your own system before the next get or is_ready.

  • How a child that sent nothing is reported. If the pipe closes without a result and the child was killed or exited non-zero, the failure reads child killed by signal N before sending a result or child exited with status N before sending a result (OOM killer, a crash in the driver, an exit in a txn_do_async body). A result that arrives but cannot be thawed, or a clean exit with no result, stays corrupt or empty result from child.

PROCESS OWNERSHIP

A Future belongs to the process that created it. The pipe and the child are that process's: it alone reads the result and reaps the child. In any other process (a copy inherited through an application fork), get, is_ready and is_failed fail with belongs to process N, where N is the owner's pid, and the destructor closes nothing and reaps nothing, so the owner still receives the whole result. A derived future (then / catch / and_then) follows its source. A future that is already resolved holds its values and can be read anywhere.

STATUS

Full future_class surface implemented: the minimal DBIO::Future contract plus the DBIO::Future::Immediate-compatible done / fail / needs_all / and_then. "then" / "catch" / "and_then" flatten a single returned DBIO::Forked::Future (chaining) but do not otherwise inspect nested structures.

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.