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

Comparing AnyEvent-DBI/README (file contents):
Revision 1.6 by root, Sat Oct 30 20:23:44 2010 UTC vs.
Revision 1.7 by root, Tue Aug 15 07:31:06 2017 UTC

… …
30 This module implements asynchronous DBI access by forking or executing 30 This module implements asynchronous DBI access by forking or executing
31 separate "DBI-Server" processes and sending them requests. 31 separate "DBI-Server" processes and sending them requests.
32 32
33 It means that you can run DBI requests in parallel to other tasks. 33 It means that you can run DBI requests in parallel to other tasks.
34 34
35 The overhead for very simple statements ("select 0") is somewhere around 35 With DBD::mysql, the overhead for very simple statements ("select 0") is
36 100% to 120% (dual/single core CPU) compared to an explicit 36 somewhere around 50% compared to an explicit
37 prepare_cached/execute/fetchrow_arrayref/finish combination. 37 prepare_cached/execute/fetchrow_arrayref/finish combination. With
38 DBD::SQlite3, it's more like a factor of 8 for this trivial statement.
38 39
39 ERROR HANDLING 40 ERROR HANDLING
40 This module defines a number of functions that accept a callback 41 This module defines a number of functions that accept a callback
41 argument. All callbacks used by this module get their AnyEvent::DBI 42 argument. All callbacks used by this module get their AnyEvent::DBI
42 handle object passed as first argument. 43 handle object passed as first argument.
43 44
44 If the request was successful, then there will be more arguments, 45 If the request was successful, then there will be more arguments,
45 otherwise there will only be the $dbh argument and $@ contains an error 46 otherwise there will only be the $dbh argument and $@ contains an error
46 message. 47 message.
47 48
48 A convinient way to check whether an error occured is to check $#_ - if 49 A convenient way to check whether an error occurred is to check $#_ - if
49 that is true, then the function was successful, otherwise there was an 50 that is true, then the function was successful, otherwise there was an
50 error. 51 error.
51 52
52 METHODS 53 METHODS
53 $dbh = new AnyEvent::DBI $database, $user, $pass, [key => value]... 54 $dbh = new AnyEvent::DBI $database, $user, $pass, [key => value]...
… …
93 94
94 When on_connect is supplied, connect error are not fatal and 95 When on_connect is supplied, connect error are not fatal and
95 AnyEvent::DBI will not "die". You still cannot, however, use the 96 AnyEvent::DBI will not "die". You still cannot, however, use the
96 $dbh object you received from "new" to make requests. 97 $dbh object you received from "new" to make requests.
97 98
98 exec_server => 1 99 fork_template => $AnyEvent::Fork-object
99 If you supply an "exec_server" argument, then the DBI server 100 "AnyEvent::DBI" uses "AnyEvent::Fork->new" to create the
100 process will fork and exec another perl interpreter (using $^X) 101 database slave, which in turn either "exec"'s a new process
101 with just the AnyEvent::DBI proxy running. This will provide the 102 (similar to the old "exec_server" constructor argument) or uses
102 cleanest possible proxy for your database server. 103 a process forked early (see AnyEvent::Fork::Early).
103 104
104 If you do not supply the "exec_server" argument (or supply it 105 With this argument you can provide your own fork template. This
105 with a false value) then the traditional method of starting the 106 can be useful if you create a lot of "AnyEvent::DBI" handles and
106 server by forking the current process is used. The forked 107 want to save memory (And speed up startup) by not having to load
107 interpreter will try to clean itself up by calling POSIX::close 108 "AnyEvent::DBI" again and again into your child processes:
108 on all file descriptors except STDIN, STDOUT, and STDERR (and 109
109 the socket it uses to communicate with the cilent, of course). 110 my $template = AnyEvent::Fork
111 ->new # create new template
112 ->require ("AnyEvent::DBI::Slave"); # preload AnyEvent::DBI::Slave module
113
114 for (...) {
115 $dbh = new AnyEvent::DBI ...
116 fork_template => $template;
110 117
111 timeout => seconds 118 timeout => seconds
112 If you supply a timeout parameter (fractional values are 119 If you supply a timeout parameter (fractional values are
113 supported), then a timer is started any time the DBI handle 120 supported), then a timer is started any time the DBI handle
114 expects a response from the server. This includes connection 121 expects a response from the server. This includes connection
… …
129 136
130 Timeout errors are always fatal. 137 Timeout errors are always fatal.
131 138
132 Any additional key-value pairs will be rolled into a hash reference 139 Any additional key-value pairs will be rolled into a hash reference
133 and passed as the final argument to the "DBI->connect (...)" call. 140 and passed as the final argument to the "DBI->connect (...)" call.
134 For example, to supress errors on STDERR and send them instead to an 141 For example, to suppress errors on STDERR and send them instead to
135 AnyEvent::Handle you could do: 142 an AnyEvent::Handle you could do:
136 143
137 $dbh = new AnyEvent::DBI 144 $dbh = new AnyEvent::DBI
138 "DBI:mysql:test;mysql_read_default_file=/root/.my.cnf", "", "", 145 "DBI:mysql:test;mysql_read_default_file=/root/.my.cnf", "", "",
139 PrintError => 0, 146 PrintError => 0,
140 on_error => sub { 147 on_error => sub {
… …
146 153
147 $dbh->timeout ($seconds) 154 $dbh->timeout ($seconds)
148 Sets (or clears, with "undef") the database timeout. Useful to 155 Sets (or clears, with "undef") the database timeout. Useful to
149 extend the timeout when you are about to make a really long query. 156 extend the timeout when you are about to make a really long query.
150 157
158 $dbh->attr ($attr_name[, $attr_value], $cb->($dbh, $new_value))
159 An accessor for the database handle attributes, such as
160 "AutoCommit", "RaiseError", "PrintError" and so on. If you provide
161 an $attr_value (which might be "undef"), then the given attribute
162 will be set to that value.
163
164 The callback will be passed the database handle and the attribute's
165 value if successful.
166
167 If an error occurs and the "on_error" callback returns, then only
168 $dbh will be passed and $@ contains the error message.
169
151 $dbh->exec ("statement", @args, $cb->($dbh, \@rows, $rv)) 170 $dbh->exec ("statement", @args, $cb->($dbh, \@rows, $rv))
152 Executes the given SQL statement with placeholders replaced by 171 Executes the given SQL statement with placeholders replaced by
153 @args. The statement will be prepared and cached on the server side, 172 @args. The statement will be prepared and cached on the server side,
154 so using placeholders is extremely important. 173 so using placeholders is extremely important.
155 174
… …
162 call. 181 call.
163 182
164 If an error occurs and the "on_error" callback returns, then only 183 If an error occurs and the "on_error" callback returns, then only
165 $dbh will be passed and $@ contains the error message. 184 $dbh will be passed and $@ contains the error message.
166 185
167 $dbh->attr ($attr_name[, $attr_value], $cb->($dbh, $new_value)) 186 $dbh->stattr ($attr_name, $cb->($dbh, $value))
168 An accessor for the handle attributes, such as "AutoCommit", 187 An accessor for the statement attributes of the most recently
169 "RaiseError", "PrintError" and so on. If you provide an $attr_value 188 executed statement, such as "NAME" or "TYPE".
170 (which might be "undef"), then the given attribute will be set to
171 that value.
172 189
173 The callback will be passed the database handle and the attribute's 190 The callback will be passed the database handle and the attribute's
174 value if successful. 191 value if successful.
175 192
176 If an error occurs and the "on_error" callback returns, then only 193 If an error occurs and the "on_error" callback returns, then only
… …
225 # otherwise, we can ignore $rc and $errcode for this particular func 242 # otherwise, we can ignore $rc and $errcode for this particular func
226 243
227SEE ALSO 244SEE ALSO
228 AnyEvent, DBI, Coro::Mysql. 245 AnyEvent, DBI, Coro::Mysql.
229 246
230AUTHOR 247AUTHOR AND CONTACT
231 Marc Lehmann <schmorp@schmorp.de> 248 Marc Lehmann <schmorp@schmorp.de> (current maintainer)
232 http://home.schmorp.de/ 249 http://home.schmorp.de/
233 250
234 Adam Rosenstein <adam@redcondor.com> 251 Adam Rosenstein <adam@redcondor.com>
235 http://www.redcondor.com/ 252 http://www.redcondor.com/
236 253

Diff Legend

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