NAME

DBIO::MySQL::EV::QueryExecutor - Query execution wrapper for DBIO MySQL async storage

VERSION

version 0.900007

DESCRIPTION

Provides a single execute($conn, $sql, $bind) interface for query execution. The connection is supplied per call by the caller (the storage acquires it from the pool, or hands over a pinned one), so the executor holds no connection state of its own and returns a Future with the result rows.

The Future is of the class passed to new as future_class -- the storage passes its "future_class" in DBIO::MySQL::EV::Storage -- and defaults to DBIO::MySQL::EV::Future. It settles from an idle watcher of the EV loop that runs after the EV::MariaDB callback of the statement (below), so its get has to be able to run the EV loop: a plain Future dies there instead.

A query with bind values goes prepare -> execute -> close_stmt ("query" in EV::MariaDB takes no binds). The close is not optional: the statement id EV::MariaDB hands out is a plain integer, so nothing frees the server-side statement when the Perl side lets go of it -- without close_stmt the server keeps every one until the connection closes, and a long-lived pool runs into the server-wide max_prepared_stmt_count, which then refuses prepares for every client of that server. A query without binds is a plain query -- except a CALL: EV::MariaDB calls back for a query with the first result set and reads the rest of the answer only after the callback, and a statement with bind values that follows on that connection is refused. A statement without bind values that begins with CALL (leading whitespace and comments allowed) goes through prepare too, so the whole answer is read when the Future settles (ADR 0010). A multi-statement text that does not begin with CALL is not recognised.

A Future settles from the loop's idle watcher, not inside the EV::MariaDB callback that delivered the answer (ADR 0001 addendum). EV::MariaDB queues a plain query issued while a callback of its handle runs and sends it only once that callback has returned, so a then or a txn_do coderef run from inside the callback could not wait for a statement it sent there. Run from the watcher they are outside every callback of the handle, the statement goes out at once, and a blocking wait for it ends. Everything of the answer that concerns the wire stays in the callback -- the close_stmt of a statement with bind values is issued there, and the Future settles after it has been answered -- and only the settling is deferred: the count of statements in flight, the Future's done or fail with the callbacks hanging off it, and the start of the statements that wait behind it ("execute_when_idle"), in that order. Settlings run oldest first, one watcher for all connections, so Futures settle in the order the handles answered; one that dies is warned about and does not stop the ones behind it. A blocking wait inside one of them runs the loop, and with it this watcher, so the settlings behind it carry on meanwhile.

It also counts, per connection, the statements it has dispatched whose Future has not settled yet. A connection with one of its settlings running (the then chain of a statement, the coderef of a txn_do) and no such statement has nothing left to do before that returns ("_waits_for_callback"). DBIO::MySQL::EV::Pool asks that of each of its connections to tell whether a caller queued for one can still be served while a blocking wait runs ("_mysql_held_by_callbacks" in DBIO::MySQL::EV::Pool).

Separated from Storage to allow independent testing of query execution logic from connection pooling and transaction orchestration.

METHODS

new

my $executor = DBIO::MySQL::EV::QueryExecutor->new(
  future_class => 'DBIO::MySQL::EV::Future',
  error_masker => \&mask,
);

error_masker is optional: a coderef called as $masker->($text, \@values, $sql, $code) that answers the text of an error with the values taken out (ADR 0075 of the core: an error names keys, columns and options, never a value; MySQL and MariaDB write the offending value into their text, a bound one included). Every error text a statement ends in goes through it before the exception is built -- the server's answer to the prepare, the execute and the query, the text of an execute that croaks, and the croak of a dispatch EV::MariaDB refuses ("execute" rethrows it masked). An exception object is passed on as it is. \@values are the bound values that can be looked for in a text -- the defined, non-reference ones of four characters or more, as plain strings, a copy: the caller's bind arrayref is not held (ADR 0044) -- and $sql the statement as it was handed over. $code is the error number of the server (1062, 1366, ...), read from the handle while it holds the error of this very statement, or undef -- for a client error (2000 to 2999), a text the handle does not carry, no handle: the server words its text in the language of its session, and the masker masks by the code, not by the wording ("mask_error_details" in DBIO::MySQL::Util). The SQLSTATE of the server's refusal stays. Without a masker the text is the engine's own. The storage passes "_mysql_mask_error" in DBIO::MySQL::EV::Storage.

execute

my $future = $executor->execute($mdb, $sql, $bind);

Execute a query on a given EV::MariaDB connection. Returns a Future that resolves with the result rows (array or arrayref).

With bind values the prepared statement is closed after execute -- after a failed execute too, and after one that croaked -- and the Future settles only once that close has completed. close_stmt is an exclusive operation, so the handle is not idle before then, and a caller that hands the connection back to the pool when the Future is ready ("_query_async" in DBIO::MySQL::EV::Storage) must not do so earlier. The Future carries the outcome of the execute: a close_stmt that croaks or reports an error settles it at once with that outcome and changes nothing about it -- an INSERT that ran is not reported as failed because its statement could not be closed. It settles exactly once.

The Future settles from the idle watcher, after the callback of the handle has returned: a statement issued by what its callbacks run -- a then, the coderef of a txn_do -- is sent at once, with or without bind values, and a blocking wait for it returns.

Every callback returns at once in a process other than the one that called execute. A forked child that resumes the EV loop finishes its copies of the pooled handles ("_create_connection" in DBIO::MySQL::EV::Pool), and EV::MariaDB calls back every statement in flight with a "connection finished" error; the child must not answer that with a close_stmt, a release into the pool or the caller's callbacks -- all of them belong to the parent. The Future stays pending in the child (ADR 0010).

reset_connection

my $future = $executor->reset_connection($mdb);

Send COM_RESET_CONNECTION on $mdb ("reset_connection" in EV::MariaDB) and return a Future that resolves with 1 once the server answered, or fails with its error. The server drops the session state of the connection (user and session variables, temporary tables, prepared statements, locks taken with GET_LOCK, an open transaction); the client library marks its statement handles closed. The operation is exclusive in EV::MariaDB, so it is counted like a statement with bind values: what is issued behind it through "execute_after_exclusive" waits for it. A dispatch EV::MariaDB refuses dies, as "execute" does. The Future settles from the idle watcher, as every other.

execute_when_idle

my $future = $executor->execute_when_idle($mdb, $sql, $bind, $timeout);

Like "execute", but behind every statement still in flight on $mdb: the statement is handed to EV::MariaDB only once the Future of the last of them has settled -- for a statement with bind values that is after its close_stmt -- and at once when none is in flight. One order per connection: statements queued this way start in the order they were queued, each after the one before it has settled.

The reason is EV::MariaDB's own: it refuses a query ("cannot queue query: exclusive operation in progress") while a prepare or an execute is in flight, and the ROLLBACK of a failed transaction is a query. The statement is started from the callback that settles the last statement in flight, after that Future was settled; a query issued there is taken and sent once the callback returned (measured live, t/37-txn-rollback-refused-live.t).

The returned Future settles with the outcome of the statement. A dispatch EV::MariaDB refuses fails it with that error, where "execute" dies. A handle that is gone before its turn, or a Future that was cancelled while it waited, means the statement is never sent; a handle that is torn down while the statement waits ("forget") fails its Future with a DBIO::Exception. With a positive $timeout (seconds) a statement that has not been started by then is not sent: its Future fails with a DBIO::Exception naming the wait. A waiting statement that sends nothing does not hold up the ones behind it: the next one starts in its place.

execute_after_exclusive

my $future = $executor->execute_after_exclusive($mdb, $sql, $bind);

Like "execute", but a statement issued while a prepare or an execute (a statement with bind values, a CALL) is in flight on $mdb, or while others wait behind a statement in flight, is queued as "execute_when_idle" queues it and handed to EV::MariaDB when the Future of the statement in flight has settled. EV::MariaDB refuses a query while such an operation is in flight (this holds for every statement of a pinned connection, not only ROLLBACK). With only plain queries in flight the statement goes out at once, pipelined behind them as before.

_waits_for_callback

my $stalled = DBIO::MySQL::EV::QueryExecutor->_waits_for_callback($mdb);

Class method. True when a settling of a Future of $mdb runs -- the idle watcher is calling what hangs off a statement's Future: a then, the coderef of a txn_do -- and no statement dispatched on $mdb is still unsettled: the connection has nothing in flight that the loop could answer, and whatever is to happen on it next waits for that to return -- a transaction's COMMIT or ROLLBACK included, which core sends only after the coderef has returned. False for a connection none of whose settlings runs, and for one with a statement in flight, whose answer may be what gives the connection back to the pool.

forget

DBIO::MySQL::EV::QueryExecutor->forget($mdb);

Class method. Drop everything the executor keeps for $mdb: the callback frame, the count of statements in flight and the statements waiting behind them ("execute_when_idle"). Called where a handle goes away -- it is shut down ("_shutdown_connection" in DBIO::MySQL::EV::Pool) or a forked child finishes its copy of it ("_create_connection" in DBIO::MySQL::EV::Pool). Those are kept per address of the handle and nothing else removes them: a count left over for a handle that never called back would be read by a later handle at the same address as work in flight. A new handle starts from nothing. Every waiting statement is failed, not run, and not left pending: its Future fails with a DBIO::Exception saying the connection was torn down and the statement not sent, oldest first. One whose Future is ready already (cancelled while it waited) is left alone. The queue is taken out before any Future is failed, so a callback of a failure may call forget or "execute_when_idle" again.

_fail_waiting

DBIO::MySQL::EV::QueryExecutor->_fail_waiting($mdb);

Class method. Take the statements waiting behind others on $mdb out of the queue and fail their Futures (see "forget"); touches nothing else the executor keeps. Called by "forget", and by "_shutdown_connection" in DBIO::MySQL::EV::Pool before finish: finish calls back the statement in flight, which would start the waiting ones against the finished handle.

_handle_code

my $code = DBIO::MySQL::EV::QueryExecutor::_handle_code($mdb, $text);

The error number of the server (EV::MariaDB's error_number) for the error $text, or undef. The handle answers only while it holds the error of the statement that is being reported: its error_message must be $text (or part of it, a croak adds its location). A number of the client library (2000 to 2999), zero, a handle without the accessors, a handle that holds another error and anything that throws all answer undef: the text is then masked by its wording alone. Read in the statement's own callback, before anything else is sent on the handle.

_server_error

my $error = DBIO::MySQL::EV::QueryExecutor::_server_error($mdb, $text, $mask);

The error of a statement as its Future fails with it (core ADR 0062): a DBIO::Exception::Server carrying the sqlstate when the server refused the statement, the text itself otherwise. It stringifies to $text with the values taken out by $mask (an optional coderef, see "new", handed the server's error number as well; the comparison with the handle's error below is made with the text as the handle holds it, the masking comes after). Called from the statement's own callback, where the handle still holds that error.

The line is drawn by the handle and the text: the handle's error_message is $text, its sqlstate is a real one (not 00000), and its error_number is a server's -- 1000 to 1999, or 3000 and up (MariaDB's own range) -- and not one of the client library's (2000 to 2999: connection lost, server gone away, commands out of sync). A client error, an object and undef pass unchanged. table, constraint and detail are not reported: the client library names none of them separately.

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.