… | |
… | |
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 | 120% to 200% (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 porxy 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 | |
227 | SEE ALSO |
244 | SEE ALSO |
228 | AnyEvent, DBI, Coro::Mysql. |
245 | AnyEvent, DBI, Coro::Mysql. |
229 | |
246 | |
230 | AUTHOR |
247 | AUTHOR 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 | |