--- AnyEvent-DBI/README 2009/06/02 16:16:03 1.4 +++ AnyEvent-DBI/README 2009/06/29 08:25:05 1.5 @@ -9,7 +9,9 @@ my $dbh = new AnyEvent::DBI "DBI:SQLite:dbname=test.db", "", ""; $dbh->exec ("select * from test where num=?", 10, sub { - my ($rows, $rv) = @_; + my ($dbh, $rows, $rv) = @_; + + $#_ or die "failure: $@"; print "@$_\n" for @$rows; @@ -25,7 +27,7 @@ This module is an AnyEvent user, you need to make sure that you use and run a supported event loop. - This module implements asynchronous DBI access my forking or executing + This module implements asynchronous DBI access by forking or executing separate "DBI-Server" processes and sending them requests. It means that you can run DBI requests in parallel to other tasks. @@ -34,6 +36,19 @@ 120% to 200% (dual/single core CPU) compared to an explicit prepare_cached/execute/fetchrow_arrayref/finish combination. + ERROR HANDLING + This module defines a number of functions that accept a callback + argument. All callbacks used by this module get their AnyEvent::DBI + handle object passed as first argument. + + If the request was successful, then there will be more arguments, + otherwise there will only be the $dbh argument and $@ contains an error + message. + + A convinient way to check whether an error occured is to check $#_ - if + that is true, then the function was successful, otherwise there was an + error. + METHODS $dbh = new AnyEvent::DBI $database, $user, $pass, [key => value]... Returns a database handle for the given database. Each database @@ -56,43 +71,53 @@ entry, $@ is set to the error message. $filename and $line is where the original request was submitted. - If the fatal argument is true then the database connection shuts - down and your database handle becomes invalid. All of your - request callbacks are called without any arguments. + If the fatal argument is true then the database connection is + shut down and your database handle became invalid. In addition + to invoking the "on_error" callback, all of your queued request + callbacks are called without only the $dbh argument. If omitted, then "die" will be called on any errors, fatal or not. - The $dbh argument is always a weak reference to the - AnyEvent::DBI object. - - on_connect => $callback->($dbh) - If you supply an on_connect callback, then this callback will be - invoked after the database connection is attempted. If the - connection succeeds, $dbh contains a weak reference to the - AnyEvent::DBI object. If the connection fails for any reason, no - arguments are passed to the callback and $@ contains - $DBI::errstr. - - Regardless of whether on_connect is supplied, connect errors - will result in on_error being called. However, if no on_connect - callback is supplied, then connection errors are considered - fatal. The client will die() and the on_error callback will be - called with $fatal true. When on_connect is supplied, connect - error are not fatal and AnyEvent::DBI will not die(). You still - cannot, however, use the $dbh object you recived from new() to - make requests. + on_connect => $callback->($dbh[, $success]) + If you supply an "on_connect" callback, then this callback will + be invoked after the database connect attempt. If the connection + succeeds, $success is true, otherwise it is missing and $@ + contains the $DBI::errstr. + + Regardless of whether "on_connect" is supplied, connect errors + will result in "on_error" being called. However, if no + "on_connect" callback is supplied, then connection errors are + considered fatal. The client will "die" and the "on_error" + callback will be called with $fatal true. + + When on_connect is supplied, connect error are not fatal and + AnyEvent::DBI will not "die". You still cannot, however, use the + $dbh object you received from "new" to make requests. + + exec_server => 1 + If you supply an "exec_server" argument, then the DBI server + process will fork and exec another perl interpreter (using $^X) + with just the AnyEvent::DBI proxy running. This will provide the + cleanest possible porxy for your database server. + + If you do not supply the "exec_server" argument (or supply it + with a false value) then the traditional method of starting the + server by forking the current process is used. The forked + interpreter will try to clean itself up by calling POSIX::close + on all file descriptors except STDIN, STDOUT, and STDERR (and + the socket it uses to communicate with the cilent, of course). timeout => seconds - If you supply a timeout parameter (floating point number of - seconds), then a timer is started any time the DBI handle + If you supply a timeout parameter (fractional values are + supported), then a timer is started any time the DBI handle expects a response from the server. This includes connection setup as well as requests made to the backend. The timeout spans the duration from the moment the first data is written (or queued to be written) until all expected responses are returned, but is postponed for "timeout" seconds each time more data is returned from the server. If the timer ever goes off then a - fatal error is generated. If you have an on_error handler + fatal error is generated. If you have an "on_error" handler installed, then it will be called, otherwise your program will die(). @@ -105,43 +130,102 @@ Timeout errors are always fatal. Any additional key-value pairs will be rolled into a hash reference - and passed as the final argument to the DBI->connect(...) call. For - example, to supress errors on STDERR and send them instead to an + and passed as the final argument to the "DBI->connect (...)" call. + For example, to supress errors on STDERR and send them instead to an AnyEvent::Handle you could do: - $dbh = new AnyEvent::DBI - "DBI:mysql:test;mysql_read_default_file=/root/.my.cnf", "", "", - PrintError => 0, - on_error => sub { $log_handle->push_write("DBI Error: $@ at $_[1]:$_[2]\n"); } - - $dbh->on_error ( $cb->($dbh, $filename, $line, $fatal) ); - Sets (or clears) the on_error handler. - - $dbh->on_connect ( $cb->($dbh) ) ; - Sets (or clears) the on_connect handler. - - $dbh->timeout ( $seconds ) ; - Sets (or clears) the database timeout. Useful to extend the timeout - when you are about to make a really long query. + $dbh = new AnyEvent::DBI + "DBI:mysql:test;mysql_read_default_file=/root/.my.cnf", "", "", + PrintError => 0, + on_error => sub { + $log_handle->push_write ("DBI Error: $@ at $_[1]:$_[2]\n"); + }; + + $dbh->on_error ($cb->($dbh, $filename, $line, $fatal)) + Sets (or clears, with "undef") the "on_error" handler. + + $dbh->timeout ($seconds) + Sets (or clears, with "undef") the database timeout. Useful to + extend the timeout when you are about to make a really long query. - $dbh->exec ("statement", @args, $cb->($dbh, \@rows, \%metadata )) + $dbh->exec ("statement", @args, $cb->($dbh, \@rows, $rv)) Executes the given SQL statement with placeholders replaced by @args. The statement will be prepared and cached on the server side, - so using placeholders is compulsory. + so using placeholders is extremely important. The callback will be called with a weakened AnyEvent::DBI object as the first argument and the result of "fetchall_arrayref" as (or "undef" if the statement wasn't a select statement) as the second - argument. Third argument is a hash reference holding metadata about - the request. Currently, the only key defined is "$metadata-"{rv}> - holding the return value of "execute". Additional metadata might be - added. + argument. + + Third argument is the return value from the "DBI->execute" method + call. + + If an error occurs and the "on_error" callback returns, then only + $dbh will be passed and $@ contains the error message. + + $dbh->attr ($attr_name[, $attr_value], $cb->($dbh, $new_value)) + An accessor for the handle attributes, such as "AutoCommit", + "RaiseError", "PrintError" and so on. If you provide an $attr_value + (which might be "undef"), then the given attribute will be set to + that value. + + The callback will be passed the database handle and the attribute's + value if successful. + + If an error occurs and the "on_error" callback returns, then only + $dbh will be passed and $@ contains the error message. + + $dbh->begin_work ($cb->($dbh[, $rc])) + $dbh->commit ($cb->($dbh[, $rc])) + $dbh->rollback ($cb->($dbh[, $rc])) + The begin_work, commit, and rollback methods expose the equivalent + transaction control method of the DBI driver. On success, $rc is + true. + + If an error occurs and the "on_error" callback returns, then only + $dbh will be passed and $@ contains the error message. + + $dbh->func ('string_which_yields_args_when_evaled', $func_name, + $cb->($dbh, $rc, $dbi_err, $dbi_errstr)) + This gives access to database driver private methods. Because they + are not standard you cannot always depend on the value of $rc or + $dbi_err. Check the documentation for your specific driver/function + combination to see what it returns. + + Note that the first argument will be eval'ed to produce the argument + list to the func() method. This must be done because the + serialization protocol between the AnyEvent::DBI server process and + your program does not support the passage of closures. + + Here's an example to extend the query language in SQLite so it + supports an intstr() function: + + $cv = AnyEvent->condvar; + $dbh->func ( + q{ + instr => 2, sub { + my ($string, $search) = @_; + return index $string, $search; + }, + }, + create_function => sub { + return $cv->send ($@) + unless $#_; + $cv->send (undef, @_[1,2,3]); + } + ); + + my ($err,$rc,$errcode,$errstr) = $cv->recv; + + die $err if defined $err; + die "EVAL failed: $errstr" + if $errcode; - If an error occurs and the "on_error" callback returns, then no - arguments will be passed and $@ contains the error message. + # otherwise, we can ignore $rc and $errcode for this particular func SEE ALSO - AnyEvent, DBI. + AnyEvent, DBI, Coro::Mysql. AUTHOR Marc Lehmann