--- AnyEvent-DBI/README	2008/12/20 21:28:57	1.3
+++ AnyEvent-DBI/README	2009/06/02 16:16:03	1.4
@@ -25,7 +25,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 by forking or executing
+    This module implements asynchronous DBI access my forking or executing
     separate "DBI-Server" processes and sending them requests.
 
     It means that you can run DBI requests in parallel to other tasks.
@@ -56,22 +56,86 @@
             entry, $@ is set to the error message. $filename and $line is
             where the original request was submitted.
 
-            If this callback returns and this was a fatal error ($fatal is
-            true) then AnyEvent::DBI die's, otherwise it calls the original
-            request callback without any arguments.
+            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 omitted, then "die" will be called on any errors, fatal or
             not.
 
-    $dbh->exec ("statement", @args, $cb->($rows, $rv, ...))
+            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.
+
+        timeout => seconds
+            If you supply a timeout parameter (floating point number of
+            seconds), 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
+            installed, then it will be called, otherwise your program will
+            die().
+
+            When altering your databases with timeouts it is wise to use
+            transactions. If you quit due to timeout while performing
+            insert, update or schema-altering commands you can end up not
+            knowing if the action was submitted to the database,
+            complicating recovery.
+
+            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
+        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->exec ("statement", @args, $cb->($dbh, \@rows, \%metadata ))
         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.
 
-        The callback will be called with the result of "fetchall_arrayref"
-        as first argument (or "undef" if the statement wasn't a select
-        statement) and the return value of "execute" as second argument.
-        Additional arguments might get passed as well.
+        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.
 
         If an error occurs and the "on_error" callback returns, then no
         arguments will be passed and $@ contains the error message.
@@ -83,3 +147,6 @@
        Marc Lehmann <schmorp@schmorp.de>
        http://home.schmorp.de/
 
+       Adam Rosenstein <adam@redcondor.com>
+       http://www.redcondor.com/
+