ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-DBI/README
(Generate patch)

Comparing AnyEvent-DBI/README (file contents):
Revision 1.3 by root, Sat Dec 20 21:28:57 2008 UTC vs.
Revision 1.4 by root, Tue Jun 2 16:16:03 2009 UTC

… …
23 23
24DESCRIPTION 24DESCRIPTION
25 This module is an AnyEvent user, you need to make sure that you use and 25 This module is an AnyEvent user, you need to make sure that you use and
26 run a supported event loop. 26 run a supported event loop.
27 27
28 This module implements asynchronous DBI access by forking or executing 28 This module implements asynchronous DBI access my forking or executing
29 separate "DBI-Server" processes and sending them requests. 29 separate "DBI-Server" processes and sending them requests.
30 30
31 It means that you can run DBI requests in parallel to other tasks. 31 It means that you can run DBI requests in parallel to other tasks.
32 32
33 The overhead for very simple statements ("select 0") is somewhere around 33 The overhead for very simple statements ("select 0") is somewhere around
… …
54 on_error => $callback->($dbh, $filename, $line, $fatal) 54 on_error => $callback->($dbh, $filename, $line, $fatal)
55 When an error occurs, then this callback will be invoked. On 55 When an error occurs, then this callback will be invoked. On
56 entry, $@ is set to the error message. $filename and $line is 56 entry, $@ is set to the error message. $filename and $line is
57 where the original request was submitted. 57 where the original request was submitted.
58 58
59 If this callback returns and this was a fatal error ($fatal is 59 If the fatal argument is true then the database connection shuts
60 true) then AnyEvent::DBI die's, otherwise it calls the original 60 down and your database handle becomes invalid. All of your
61 request callback without any arguments. 61 request callbacks are called without any arguments.
62 62
63 If omitted, then "die" will be called on any errors, fatal or 63 If omitted, then "die" will be called on any errors, fatal or
64 not. 64 not.
65 65
66 The $dbh argument is always a weak reference to the
67 AnyEvent::DBI object.
68
69 on_connect => $callback->($dbh)
70 If you supply an on_connect callback, then this callback will be
71 invoked after the database connection is attempted. If the
72 connection succeeds, $dbh contains a weak reference to the
73 AnyEvent::DBI object. If the connection fails for any reason, no
74 arguments are passed to the callback and $@ contains
75 $DBI::errstr.
76
77 Regardless of whether on_connect is supplied, connect errors
78 will result in on_error being called. However, if no on_connect
79 callback is supplied, then connection errors are considered
80 fatal. The client will die() and the on_error callback will be
81 called with $fatal true. When on_connect is supplied, connect
82 error are not fatal and AnyEvent::DBI will not die(). You still
83 cannot, however, use the $dbh object you recived from new() to
84 make requests.
85
86 timeout => seconds
87 If you supply a timeout parameter (floating point number of
88 seconds), then a timer is started any time the DBI handle
89 expects a response from the server. This includes connection
90 setup as well as requests made to the backend. The timeout spans
91 the duration from the moment the first data is written (or
92 queued to be written) until all expected responses are returned,
93 but is postponed for "timeout" seconds each time more data is
94 returned from the server. If the timer ever goes off then a
95 fatal error is generated. If you have an on_error handler
96 installed, then it will be called, otherwise your program will
97 die().
98
99 When altering your databases with timeouts it is wise to use
100 transactions. If you quit due to timeout while performing
101 insert, update or schema-altering commands you can end up not
102 knowing if the action was submitted to the database,
103 complicating recovery.
104
105 Timeout errors are always fatal.
106
107 Any additional key-value pairs will be rolled into a hash reference
108 and passed as the final argument to the DBI->connect(...) call. For
109 example, to supress errors on STDERR and send them instead to an
110 AnyEvent::Handle you could do:
111
112 $dbh = new AnyEvent::DBI
113 "DBI:mysql:test;mysql_read_default_file=/root/.my.cnf", "", "",
114 PrintError => 0,
115 on_error => sub { $log_handle->push_write("DBI Error: $@ at $_[1]:$_[2]\n"); }
116
117 $dbh->on_error ( $cb->($dbh, $filename, $line, $fatal) );
118 Sets (or clears) the on_error handler.
119
120 $dbh->on_connect ( $cb->($dbh) ) ;
121 Sets (or clears) the on_connect handler.
122
123 $dbh->timeout ( $seconds ) ;
124 Sets (or clears) the database timeout. Useful to extend the timeout
125 when you are about to make a really long query.
126
66 $dbh->exec ("statement", @args, $cb->($rows, $rv, ...)) 127 $dbh->exec ("statement", @args, $cb->($dbh, \@rows, \%metadata ))
67 Executes the given SQL statement with placeholders replaced by 128 Executes the given SQL statement with placeholders replaced by
68 @args. The statement will be prepared and cached on the server side, 129 @args. The statement will be prepared and cached on the server side,
69 so using placeholders is compulsory. 130 so using placeholders is compulsory.
70 131
71 The callback will be called with the result of "fetchall_arrayref" 132 The callback will be called with a weakened AnyEvent::DBI object as
72 as first argument (or "undef" if the statement wasn't a select 133 the first argument and the result of "fetchall_arrayref" as (or
73 statement) and the return value of "execute" as second argument. 134 "undef" if the statement wasn't a select statement) as the second
74 Additional arguments might get passed as well. 135 argument. Third argument is a hash reference holding metadata about
136 the request. Currently, the only key defined is "$metadata-"{rv}>
137 holding the return value of "execute". Additional metadata might be
138 added.
75 139
76 If an error occurs and the "on_error" callback returns, then no 140 If an error occurs and the "on_error" callback returns, then no
77 arguments will be passed and $@ contains the error message. 141 arguments will be passed and $@ contains the error message.
78 142
79SEE ALSO 143SEE ALSO
… …
81 145
82AUTHOR 146AUTHOR
83 Marc Lehmann <schmorp@schmorp.de> 147 Marc Lehmann <schmorp@schmorp.de>
84 http://home.schmorp.de/ 148 http://home.schmorp.de/
85 149
150 Adam Rosenstein <adam@redcondor.com>
151 http://www.redcondor.com/
152

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines