NAME

DBIO::Async - Shared, loop-agnostic async layer for DBIO drivers

VERSION

version 0.900007

SYNOPSIS

See DBIO::Async::Storage for the subclass contract and the seam hooks a DB-specific driver supplies.

DESCRIPTION

Shared, loop-agnostic async layer for DBIO drivers. This distribution carries the Future / Future::IO requirements and the generic async plumbing that every DB-specific async driver needs, so a sync-only driver pulls no async dependencies.

The future_io async mode (ADR 0030) resolves its transport adapter by convention: a schema connected with { async => 'future_io' } uses the per-driver adapter class ref($storage) . '::Async' for its *_async methods -- e.g. a PostgreSQL storage DBIO::PostgreSQL::Storage resolves DBIO::PostgreSQL::Storage::Async. Loading this module does not globally register future_io for every driver; it provides the shared abstract backend those per-driver adapters subclass. A driver with no such adapter croaks early and clearly. There is no auto-fallback and no async_backend/async_fallback -- the mode is explicit or the connection stays synchronous.

use DBIO::Async;   # provides the shared future_io backend base

my $schema = MyApp::Schema->connect(
    $dsn, $user, $pass, { async => 'future_io' },
);

$schema->resultset('Artist')->all_async->then(sub { ... });

The async work lives in DBIO::Async::Storage, a concrete, DB-agnostic skeleton subclassing core DBIO::Storage::Async. The generic CRUD runner, transaction pinning, pipeline bracketing and the sync ->get fallbacks are inherited from that core class (core ADR 0030, section 4); DBIO::Async::Storage adds the Future::IO transport -- query execution over the watcher seam, the listen watch loop -- the connection pool (DBIO::Async::Pool) and the AccessBroker connect-info wiring. A DB-specific driver subclasses it as DBIO::X::Storage::Async and supplies only the DB-specific seam hooks (how to submit an async query, collect the ready result, the socket fd to watch, SQL transform, connect-info shape).

EVENT LOOP COMPATIBILITY

The watcher seam is loop-agnostic: Future::IO runs on its built-in implementation -- a plain select loop of its own, no event loop -- until an implementation is loaded: use Future::IO::Impl::IOAsync; in the program (likewise for AnyEvent, Mojolicious, UV or Glib), or Future::IO->load_best_impl called once by the main program. Installing a Future::IO::Impl::* module alone changes nothing, and this distribution loads none. The user picks the loop; no event loop is a hard requirement (core ADR 0014). What the implementations do differently with this transport's polls is listed in "FUTURE::IO IMPLEMENTATIONS" in DBIO::Async::Storage.

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.