/ 
DBIx-QuickORM-0.000023
⭐ Starred 0 / DBIx::QuickORM::STH::Fork

NAME

DBIx::QuickORM::STH::Fork - Statement handle backed by a forked child process.

DESCRIPTION

An asynchronous statement-handle variant whose query runs in a forked child process that streams JSON-encoded messages back over a pipe. Every message is an envelope with exactly one key: result (always first, the driver result), row (one row), then a terminal done on success or error on failure. The terminal frame lets the parent tell a clean end from a child that died mid-stream: end-of-file with no terminal frame is reported as a truncated result rather than silently looking like the last row. ready peeks the pipe without blocking, result and row fetches block on it. Finalizing the handle drains the pipe, reaps the child, and releases the connection's fork slot; cancelling additionally signals the child with TERM.

The reap, cancel, and slot-release operations are guarded by the owning process id: if the owner forks again the child inherits this object, and its destructor must not disturb the owner's child process or connection state.

SYNOPSIS

while (my $row_hr = $sth->next) { ... }

ATTRIBUTES

connection

The owning connection.

source

The source the rows belong to.

only_one

When true, more than one row is an error.

dialect

The dialect, lazily taken from the connection.

ready

True once the result message has been read from the pipe.

got_result

The driver result once it has been read; absent until then.

done

True once iteration has finished and the handle has been finalized.

pid

PID of the forked child process.

owner_pid

PID of the process that created this handle. Reap/cancel/clear operations no-op unless they run in this process, so an inherited copy in a forked child cannot disturb the owner's child process or connection state.

on_finish

Optional parent-side completion callback. It runs once, in the owning process, after the child has completed cleanly (used to apply row-cache maintenance for a forked write, where the work happened in the child but the parent owns the cache). It is skipped if the child errored or its stream was truncated.

pipe

The pipe object messages are read from.

PUBLIC METHODS

$bool = $sth->cancel_supported

Always true: a forked query can be cancelled by signalling the child.

$dialect = $sth->dialect

The dialect, lazily taken from the connection.

$sth->clear

Release the fork slot on the owning connection.

$sth->init

Constructor hook that validates required attributes.

$bool = $sth->in_owner_process

True when running in the process that created this handle. The reap/cancel/ clear operations are no-ops elsewhere so an inherited copy in a forked child cannot disturb the owner's child process or connection state.

$bool = $sth->ready

Non-blocking peek at the pipe; true once the result message has been read.

$result = $sth->result

Block on the pipe until the result message arrives, caching and returning it.

$sth->cancel

Signal and reap the child process and finalize the handle.

$row_hr = $sth->next

Return the next row as a hashref, or undef once exhausted. With only_one set, a second row is an error.

PRIVATE METHODS

$row_hr = $sth->_next

Read and decode the next row message from the pipe, finalizing when the child signals exhaustion.

$msg = $sth->_read_message($blocking)

Read one raw message from the pipe, blocking or not per the argument.

$result = $sth->_decode_result($msg)

Decode the JSON result message and return its result payload, croaking on invalid data.

$sth->_croak_child_error($message)

Croak reporting an error the forked child sent back over the pipe.

$bool = $sth->cancel_on_destroy

False when an on_finish callback is set: such a handle wraps a write that must run to completion, so its destructor waits for the child instead of signalling it.

$sth->set_done

Drive the stream to its terminal frame (when nothing else has), reap the child, release the fork slot, mark the handle done, and run any on_finish callback if the child completed cleanly. Idempotent.

PRIVATE METHODS (cont.)

$sth->_drive_to_terminal

Read and discard frames until the terminal done or error frame (or EOF), recording whether the child finished cleanly. Used by set_done for handles whose stream nobody iterated, such as forked writes. Warns rather than croaks on an unclean end, since it usually runs from a destructor.

$sth->_terminate_unclean($message)

Mark the stream terminated without a clean completion and warn. Used when the child errored or died while set_done was draining the pipe.

SOURCE

The source code repository for DBIx::QuickORM can be found at https://github.com/exodist/DBIx-QuickORM.

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

Copyright Chad Granum <exodist7@gmail.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See https://dev.perl.org/licenses/