NAME

DBIx::QuickORM::Row::Async - Placeholder that swaps itself for a real row once async results arrive.

DESCRIPTION

A transparent proxy returned for an asynchronous single-row query. It holds an async statement handle and, once results are ready, materializes the real row and swaps itself out in place via the $_[0] alias, so callers transparently end up holding the real row object. Until then it forwards method calls, isa, can, and DOES to the eventual row's class. If the query returns no data or is cancelled the proxy becomes invalid: boolean context is false and method calls croak.

Construction requires an async handle implementing DBIx::QuickORM::Role::Async. Optional auto_refresh refreshes the row once materialized; state_method (default state_select_row) and state_args control how the connection builds the row.

SYNOPSIS

my $row = $async_row;       # placeholder, true while pending/valid
print $row->column;         # swaps in the real row, then forwards

PUBLIC METHODS

$bool = $row->isa($class)

True if the eventual row would satisfy the isa check; swaps the proxy out once results are ready.

$code = $row->can($method)

Forward can to the eventual row's class; swaps the proxy out once results are ready.

$bool = $row->DOES($role)

Forward DOES to the eventual row's class; swaps the proxy out once results are ready.

$row = DBIx::QuickORM::Row::Async->new(async => $async, ...)

Construct a placeholder around an async handle. Requires async; accepts auto_refresh, state_method, and state_args.

$async = $row->async

The underlying async statement handle.

$bool = $row->auto_refresh

Whether the materialized row will be refreshed.

$bool = $row->is_invalid

$bool = $row->is_valid

Validity of the (materialized) row; both swap the proxy out first.

$row_or_bool = $row->ready

Returns the materialized row if results are ready (or 1 when already invalid), undef while still pending.

$real_row = $row->row

Pull the single row from the async handle and build the real row object (refreshing it when auto_refresh is set), or undef if no data arrived.

$row = $row->swapout

Materialize the real row and replace the proxy in the caller's slot via the $_[0] alias, returning the real row (or the proxy itself when still invalid or pending).

$row->cancel

Cancel the in-flight async query and mark the proxy invalid.

PRIVATE METHODS

AUTOLOAD

Swap the proxy out for the real row and forward the called method to it, croaking if the proxy is invalid.

DESTROY

Drop the async handle and mark the proxy invalid if it never materialized.

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/