NAME
DBIO::Forked::Storage - Fork-per-query async storage - make any sync DBIO driver async
VERSION
version 0.900007
DESCRIPTION
Fork-based async storage backend subclassing core DBIO::Storage::Async. It makes any sync DBIO driver async without an async-capable client and without an event loop, via fork()-per-query (Model A, see DBIO::Forked): the child runs the driver's ordinary sync CRUD through the inherited sync storage, which reconnects itself in the child (see docs/adr/0002; the backend holds no connect info, see "connect_info") -- no SQL is re-implemented here -- serializes the result rows back over a pipe with Storable, and exits; the parent returns a DBIO::Forked::Future bound to the pipe read fd.
METHODS
new
my $storage = DBIO::Forked::Storage->new($schema);
Construct the fork-based async backend for $schema. The schema reference is weakened (the schema owns the storage, not the other way round). Connect info is supplied separately via "connect_info".
future_class
Returns 'DBIO::Forked::Future' -- the loop-free, pipe-backed Future this backend hands out.
connect_info
$storage->connect_info([ $dsn, $user, $pass, \%attrs, \%dbio_opts ]);
$storage->connect_info([ $broker ]);
$storage->connect_info([ $broker, \%options ]);
Take the connect info the core resolver hands over (the sync storage's _connect_info) and keep its form only: whether it is an DBIO::AccessBroker invocation, and how many elements it has. The backend holds no access data -- no DSN, user, password, attribute, broker object or options hash. Returns the form, a hash reference
{ broker => 0|1, elements => $n }
and the same again when called without an argument; before the first call it returns undef.
The form is all there is to keep because the forked child runs the inherited sync storage's own CRUD, and that storage reconnects itself in the child via its inherited fork handling (see docs/adr/0002), asking the broker again and applying the options beside it itself.
async_option_names
my @names = DBIO::Forked::Storage->async_option_names; # statement_timeout max_in_flight
The connect options this backend takes beside the core's (see "async_option_names" in DBIO::Storage::Async), given at connect time in the hash form, the DBI form's attribute hash or beside an AccessBroker:
MyApp::Schema->connect($dsn, $user, $pass, {
async => 'forked', statement_timeout => 5, max_in_flight => 4,
});
statement_timeoutA number of seconds above 0; the default is none. Every forked call carries the deadline from the moment it forks. A future still unresolved when it runs out is ended the way "cancel" in DBIO::Forked::Future ends it (SIGTERM, SIGKILL after one second, reaped) and fails with
statement_timeout exceeded. The future checks the clock when it is asked (get,is_ready,is_failed), so the deadline holds for whoever collects the result. The database decides what becomes of the statement whose client was ended; a transaction that had not committed is rolled back by the server.max_in_flightA positive integer; the default is no limit. The number of forked calls that may be unresolved at once. A call made when that many are running fails, before anything is forked, with
max_in_flight reached; it takes a slot again when one of them has resolved, been cancelled or been dropped. The limit is per connection and per process: a process forked by the application counts its own.
Processes and connections per call. Every *_async call (and every txn_do_async) forks one child, and that child opens one database connection of its own and runs the connection actions (on_connect_do / on_connect_call) on it. N unresolved calls are N processes and N connections beside the parent's own, and the server sees N logins at once. max_in_flight bounds N.
Both values are checked when the connect info is read, which is at first async use. An invalid value fails with a message that names the option and leaves the value out.
transport_capabilities
my @caps = DBIO::Forked::Storage->transport_capabilities;
Returns broker_connect_options, and nothing else.
broker_connect_options is the one capability core reads itself rather than an async layer: a transport declaring it takes the connect options given beside an DBIO::AccessBroker -- connect($broker, \%options) -- and has them on every connection it opens. Without the declaration core refuses a broker-backed connection whose options carry DBD attributes or pool_size at its first async use ("_async_storage" in DBIO::Storage::DBI).
Model A keeps that promise with no code of its own. The only connection a query ever runs on is the one the sync storage opens in the forked child, and that storage asks the broker again and joins the options beside it into the answer on every connect -- the same arguments its connection in the parent got. pool_size sizes nothing here, with a broker as with a DSN: there is no pool (pool croaks); it is accepted and stays out of the child's DBI->connect.
Still no capability an async layer could require; see "TRANSPORT CAPABILITIES AND ASYNC LAYERS".
deploy_async
Refused, synchronously, at the call: the forked backend does not deploy. The inherited deploy runs through deploy_async, so it is refused with the same message. Deploy through the sync owner instead, $schema->deploy, which works on a connection opened with { async => 'forked' } as on any other. Without this override core would refuse with Subclass must override _ddl_class, an instruction to transport authors that says nothing to a caller.
select_async
my $future = $storage->select_async($source, $select, $where, $attrs);
Run a SELECT in a forked child and return a DBIO::Forked::Future of the result rows.
select_single_async
Like "select_async" but resolves to the first row only.
insert_async
my $future = $storage->insert_async($source, \%vals);
update_async
my $future = $storage->update_async($source, \%vals, \%where);
delete_async
my $future = $storage->delete_async($source, \%where);
txn_do_async
my $future = $storage->txn_do_async(sub { ... }, @args);
Run a whole transaction in a single forked child. Mechanically identical to the CRUD path: the child runs the inherited sync storage's ordinary txn_do($body, @args) (core wraps BEGIN / body / COMMIT|ROLLBACK + retry in a BlockRunner), so BEGIN, the body and COMMIT/ROLLBACK all execute on the child's own freshly-reconnected sync connection. The $body closure does not cross the process boundary as data -- it is inherited through fork() from parent memory and runs in the child; it is called as $body->(@args) and receives no storage argument (it closes over $schema/$storage).
Two limits the caller must respect:
The body's return value must be Storable-serializable -- scalars or plain array/hash refs of scalars. It is frozen back over the pipe, so a live
Row/ResultSetobject (which drags its storage and live DB handle along) cannot cross: such a return surfaces as a failed Future with a clear message from "get" in DBIO::Forked::Future (see_serialization_error). Return plain data (ids, hashrefs of column values), not live result objects.The body must use sync operations only. Calling a
*_asyncmethod inside the body would fork again from within the child. Nothing refuses that, and the nested statement then runs in a child of its own, on a connection of its own that never saw theBEGIN-- outside the transaction. Use the ordinary sync CRUD ($schema->resultset(...)->...) inside atxn_do_asyncbody.
ACTIVATION
Loading this module (or DBIO::Forked) registers a generic forked async mode on the core base storage class (ADR 0030):
DBIO::Storage::DBI->register_async_mode( forked => 'DBIO::Forked::Storage' );
so every DBIO driver inherits it. A connection then opts in per-connection, at connect time:
my $schema = MyApp::Schema->connect($dsn, $user, $pass, { async => 'forked' });
Nothing is auto-wired: a connection opened without { async => 'forked' } stays fully synchronous (its *_async methods croak). When the mode is chosen, the core resolver in DBIO::Storage::DBI constructs __PACKAGE__->new($schema) as the embedded async backend and feeds it the sync storage's DBI-form connect info via "connect_info"; that backend then answers the six *_async methods.
STATUS
All six *_async entry points are implemented (with their sync ->get wrappers): each forks per query and roundtrips through _run_forked and DBIO::Forked::Future. "txn_do_async" runs the whole transaction in one child; see the two caller-facing limits documented on it.
Model A needs a real fork(): on a perl whose $Config{d_fork} is unset (a pseudo-fork emulated with threads) every *_async call croaks before it forks anything.
TRANSPORT CAPABILITIES AND ASYNC LAYERS
This backend advertises no transport capability an async layer could require. That is deliberate, not an omission. The one name "transport_capabilities" returns, broker_connect_options, is read by core and not by layers ("transport_capabilities" in DBIO::Storage::Async): it says that the connect options given beside an DBIO::AccessBroker reach every connection a query runs on, which Model A gets from the sync storage in the child. It describes no query path and gives a layer nothing to compose on; everything below is about the capabilities layers ask for.
Async storage layers -- the async mirrors of a driver extension -- declare what they need from a transport via required_transport_capabilities, and the capability gate in DBIO::Storage::DBI->_async_storage refuses to compose a layer onto a transport that is missing one (ADR 0032 section 5 and its addendum). Under { async => 'forked' } that gate therefore croaks for every layer that declares a requirement -- and, since the addendum, for every layer that declares nothing at all: silence is now read as "needs the default seam _query_async", not as "needs nothing". The only opt-out is an explicit empty required_transport_capabilities -- an assertion the layer's author makes and is responsible for, not something the gate infers from silence. It is right to croak in both cases.
The reason is the execution seam, not a missing feature. Those layers compose on the pooled-transport seam: they wrap _query_async on a backend that owns the query path -- and only that; _transform_sql is transport-internal dialect shaping that no layer ever calls (ADR 0032 section 6). Model A has no such seam. It overrides the six *_async methods directly and runs the driver's ordinary sync CRUD in the forked child (see "txn_do_async" and docs/adr/0002), so there is no _query_async for a layer to wrap: a layer composed here would load, compose and then quietly do nothing -- exactly the silent feature loss the gate exists to prevent.
The question is therefore not "which capability should DBIO::Forked declare" but "can an async layer compose onto Model A at all", and as things stand the answer is no -- forked serves a different seam. Note also which side owns what: engine capabilities belong to the driver's sync storage (an async backend reaches them through _owner_storage), while transport capabilities describe what the backend's own query path offers. Model A has no query path of its own to describe, and that is the point.
For callers:
An extension whose async mirror declares
required_transport_capabilitiescannot ride theforkedmode. Use a transport that owns the query path (future_io,ev), or run that extension's work synchronously.Do not "fix" the croak by advertising a capability here. Advertising one that this backend cannot honour lets the layer compose and then not work, turning a loud and accurate refusal into a silent failure.
broker_connect_optionsis no precedent for it: that one is honoured, and no layer asks for it.Making Model A layerable at all would need its own capability axis -- a name for "the child runs the driver's sync CRUD" -- that a forked-aware layer would require. That is a core / family-wide decision, and only worth making once somebody actually builds such a layer.
A layer that genuinely needs nothing from the transport can say so with an explicit empty
required_transport_capabilitieslist -- that declaration, not silence, is what the gate now accepts as "compose me anywhere". It is the only route by which this distribution could ever carry a layer without first needing the capability axis from the previous point.
CONNECTION ACTIONS IN THE CHILD
Connection actions configured on the sync storage -- on_connect_do and on_connect_call -- run again in every forked child, with no code in this distribution and nothing for the caller to enable. It falls out of Model A: the child's first DB op goes through the inherited sync storage, whose _verify_pid sees the new PID and makes _get_dbh reconnect; that reconnect is the ordinary _connect, which calls _run_connection_actions. Every child therefore starts from a connection set up exactly like the parent's -- session settings, encodings, SET search_path, a connect_call_* method (see docs/adr/0002 and its addendum, covered by t/05-sqlite-live.t).
This is not the on_connect_replay transport capability, and this backend does not advertise it. That capability makes a different promise -- a pooled transport replaying connect actions onto connections it opens outside the sync connect path -- and advertising it here would let layers compose that cannot work over Model A (see "TRANSPORT CAPABILITIES AND ASYNC LAYERS").
ROTATING BROKERS AND AN EXPIRED LEASE
The child asks the DBIO::AccessBroker again for the connection it opens, and whatever it fetches dies with it: the child is a copy, so a refresh done there never reaches the parent. If the parent holds a lease that has run out (needs_refresh true in the parent) and issues only *_async calls, every forked query therefore refreshes the broker itself -- with DBIO::AccessBroker::Vault, one vault read and one new lease per query -- while the parent's broker stays unchanged and still considers its lease expired. Only a reconnect of the parent (which asks the broker itself) ends that; its later children inherit the new lease and read nothing. While the lease is good, no child reads the vault. This follows from Model A (one connection per child, no pool, no shared state) and is pinned in t/09-broker-in-child.t, section 3. An alternative, the parent refreshing before it forks, is not implemented.
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.