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

Comparing cvsroot/AnyEvent-GDB/README (file contents):
Revision 1.1 by root, Sun Dec 23 03:25:40 2012 UTC vs.
Revision 1.2 by root, Mon Dec 31 13:01:22 2012 UTC

1NAME 1NAME
2 AnyEvent::DBI - asynchronous DBI access 2 AnyEvent::GDB - asynchronous GDB machine interface interface
3 3
4SYNOPSIS 4SYNOPSIS
5 use AnyEvent::DBI; 5 use AnyEvent::GDB;
6
7 my $cv = AnyEvent->condvar;
8
9 my $dbh = new AnyEvent::DBI "DBI:SQLite:dbname=test.db", "", "";
10
11 $dbh->exec ("select * from test where num=?", 10, sub {
12 my ($dbh, $rows, $rv) = @_;
13
14 $#_ or die "failure: $@";
15
16 print "@$_\n"
17 for @$rows;
18
19 $cv->broadcast;
20 });
21
22 # asynchronously do sth. else here
23
24 $cv->wait;
25 6
26DESCRIPTION 7DESCRIPTION
27 This module is an AnyEvent user, you need to make sure that you use and 8 This module is an AnyEvent user, you need to make sure that you use and
28 run a supported event loop. 9 run a supported event loop.
29 10
30 This module implements asynchronous DBI access by forking or executing 11 It implements the GDB MI protocol, which can be used to talk to GDB
31 separate "DBI-Server" processes and sending them requests. 12 without having to parse the ever changing command syntax aimed at
13 humans.
32 14
33 It means that you can run DBI requests in parallel to other tasks. 15 It properly quotes your commands and parses the data structures returned
16 by GDB.
34 17
35 The overhead for very simple statements ("select 0") is somewhere around 18 At the moment, it's in an early stage of development, so expect changes,
36 100% to 120% (dual/single core CPU) compared to an explicit 19 and, over time, further features (such as breakpoint-specific callbacks
37 prepare_cached/execute/fetchrow_arrayref/finish combination. 20 and so on).
38 21
39 ERROR HANDLING 22EXAMPLE PROGRAM
40 This module defines a number of functions that accept a callback 23 To get you started, here is an example program that runs /bin/ls,
41 argument. All callbacks used by this module get their AnyEvent::DBI 24 displaying the stopped information when hitting a breakpoint on "_exit":
42 handle object passed as first argument.
43 25
44 If the request was successful, then there will be more arguments, 26 use Data::Dump;
45 otherwise there will only be the $dbh argument and $@ contains an error 27 use AnyEvent::GDB;
46 message.
47 28
48 A convinient way to check whether an error occured is to check $#_ - if 29 our $gdb = new AnyEvent::GDB
49 that is true, then the function was successful, otherwise there was an 30 trace => 1,
50 error. 31 on_exec_stopped => sub {
32 ddx $_[0];
33 },
34 ;
35
36 my $done
37
38 ddx $gdb->cmd_sync (file_exec_and_symbols => "/bin/ls");
39 ddx $gdb->cmd_sync (break_insert => "_exit");
40 ddx $gdb->cmd_sync ("exec_run");
41
42 AE::cv->recv;
43
44 PROTOCOL QUIRKS
45 Minus vs. underscores
46 The MI protocol uses "-" to separate name components, while in Perl, you
47 use "_" for this purpose.
48
49 This module usually accepts either form as input, and always converts
50 names with "-" to names with "_", so the "library-loaded" notify might
51 become "notify_library_loaded", and the "host-name" result in that event
52 is stored in the "host_name" hash element in Perl.
53
54 Output redirection
55 Unfortunately, GDB has no (portable) provision to separate GDB
56 input/output from program input/output. Obviously, without a distinction
57 between program I/O and GDB I/O it becomes impossible to safely control
58 GDB.
59
60 There are two ways for you around it: redirect stdin/stdout yourself, or
61 set a tty (eg. with the "inferior_set_tty" command).
62
63 Unfortunately, the MI interface does not seem to support any kind of I/O
64 redirection, so this module helps you a bit, by setting the
65 "exec-wrapper" variable with a console "set" commmand. That is, this
66 module does soemthing like this for you, providing proper file
67 descriptors fpr your actual stdin and stdout:
68
69 set exec-wrapper <&5 >&6
70
71 The actual I/O redirection operators are also stored in "$gdb->{stdio}",
72 so you can even do it yourself, e.gh. when providing your own wrapper:
73
74 $self->cmd_raw ("set exec-wrapper $self->{stdio}", sub { });
75
76 (You need to use a raw command, as the "correct" "gdb_set" MI command
77 silently ignores any "exec-wrapper" setting).
51 78
52 METHODS 79 METHODS
53 $dbh = new AnyEvent::DBI $database, $user, $pass, [key => value]... 80 $gdb = new AnyEvent::GDB key => value...
54 Returns a database handle for the given database. Each database 81 Create a new GDB object using the given named parameters.
55 handle has an associated server process that executes statements in
56 order. If you want to run more than one statement in parallel, you
57 need to create additional database handles.
58 82
59 The advantage of this approach is that transactions work as state is 83 For initial experiments, it is highly recommended to run with
60 preserved. 84 tracing or at least "verbose" enabled. And don't forget to provide
85 an "on_eof" callback.
61 86
62 Example:
63
64 $dbh = new AnyEvent::DBI 87 my $gdb = new AnyEvent::GDB
65 "DBI:mysql:test;mysql_read_default_file=/root/.my.cnf", "", "";
66
67 Additional key-value pairs can be used to adjust behaviour:
68
69 on_error => $callback->($dbh, $filename, $line, $fatal)
70 When an error occurs, then this callback will be invoked. On
71 entry, $@ is set to the error message. $filename and $line is
72 where the original request was submitted.
73
74 If the fatal argument is true then the database connection is
75 shut down and your database handle became invalid. In addition
76 to invoking the "on_error" callback, all of your queued request
77 callbacks are called without only the $dbh argument.
78
79 If omitted, then "die" will be called on any errors, fatal or
80 not.
81
82 on_connect => $callback->($dbh[, $success])
83 If you supply an "on_connect" callback, then this callback will
84 be invoked after the database connect attempt. If the connection
85 succeeds, $success is true, otherwise it is missing and $@
86 contains the $DBI::errstr.
87
88 Regardless of whether "on_connect" is supplied, connect errors
89 will result in "on_error" being called. However, if no
90 "on_connect" callback is supplied, then connection errors are
91 considered fatal. The client will "die" and the "on_error"
92 callback will be called with $fatal true.
93
94 When on_connect is supplied, connect error are not fatal and
95 AnyEvent::DBI will not "die". You still cannot, however, use the
96 $dbh object you received from "new" to make requests.
97
98 exec_server => 1
99 If you supply an "exec_server" argument, then the DBI server
100 process will fork and exec another perl interpreter (using $^X)
101 with just the AnyEvent::DBI proxy running. This will provide the
102 cleanest possible proxy for your database server.
103
104 If you do not supply the "exec_server" argument (or supply it
105 with a false value) then the traditional method of starting the
106 server by forking the current process is used. The forked
107 interpreter will try to clean itself up by calling POSIX::close
108 on all file descriptors except STDIN, STDOUT, and STDERR (and
109 the socket it uses to communicate with the cilent, of course).
110
111 timeout => seconds
112 If you supply a timeout parameter (fractional values are
113 supported), then a timer is started any time the DBI handle
114 expects a response from the server. This includes connection
115 setup as well as requests made to the backend. The timeout spans
116 the duration from the moment the first data is written (or
117 queued to be written) until all expected responses are returned,
118 but is postponed for "timeout" seconds each time more data is
119 returned from the server. If the timer ever goes off then a
120 fatal error is generated. If you have an "on_error" handler
121 installed, then it will be called, otherwise your program will
122 die().
123
124 When altering your databases with timeouts it is wise to use
125 transactions. If you quit due to timeout while performing
126 insert, update or schema-altering commands you can end up not
127 knowing if the action was submitted to the database,
128 complicating recovery.
129
130 Timeout errors are always fatal.
131
132 Any additional key-value pairs will be rolled into a hash reference
133 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
135 AnyEvent::Handle you could do:
136
137 $dbh = new AnyEvent::DBI
138 "DBI:mysql:test;mysql_read_default_file=/root/.my.cnf", "", "",
139 PrintError => 0,
140 on_error => sub { 88 on_eof => sub {
141 $log_handle->push_write ("DBI Error: $@ at $_[1]:$_[2]\n"); 89 print Qe are done.\n";
142 };
143
144 $dbh->on_error ($cb->($dbh, $filename, $line, $fatal))
145 Sets (or clears, with "undef") the "on_error" handler.
146
147 $dbh->timeout ($seconds)
148 Sets (or clears, with "undef") the database timeout. Useful to
149 extend the timeout when you are about to make a really long query.
150
151 $dbh->exec ("statement", @args, $cb->($dbh, \@rows, $rv))
152 Executes the given SQL statement with placeholders replaced by
153 @args. The statement will be prepared and cached on the server side,
154 so using placeholders is extremely important.
155
156 The callback will be called with a weakened AnyEvent::DBI object as
157 the first argument and the result of "fetchall_arrayref" as (or
158 "undef" if the statement wasn't a select statement) as the second
159 argument.
160
161 Third argument is the return value from the "DBI->execute" method
162 call.
163
164 If an error occurs and the "on_error" callback returns, then only
165 $dbh will be passed and $@ contains the error message.
166
167 $dbh->attr ($attr_name[, $attr_value], $cb->($dbh, $new_value))
168 An accessor for the handle attributes, such as "AutoCommit",
169 "RaiseError", "PrintError" and so on. If you provide an $attr_value
170 (which might be "undef"), then the given attribute will be set to
171 that value.
172
173 The callback will be passed the database handle and the attribute's
174 value if successful.
175
176 If an error occurs and the "on_error" callback returns, then only
177 $dbh will be passed and $@ contains the error message.
178
179 $dbh->begin_work ($cb->($dbh[, $rc]))
180 $dbh->commit ($cb->($dbh[, $rc]))
181 $dbh->rollback ($cb->($dbh[, $rc]))
182 The begin_work, commit, and rollback methods expose the equivalent
183 transaction control method of the DBI driver. On success, $rc is
184 true.
185
186 If an error occurs and the "on_error" callback returns, then only
187 $dbh will be passed and $@ contains the error message.
188
189 $dbh->func ('string_which_yields_args_when_evaled', $func_name,
190 $cb->($dbh, $rc, $dbi_err, $dbi_errstr))
191 This gives access to database driver private methods. Because they
192 are not standard you cannot always depend on the value of $rc or
193 $dbi_err. Check the documentation for your specific driver/function
194 combination to see what it returns.
195
196 Note that the first argument will be eval'ed to produce the argument
197 list to the func() method. This must be done because the
198 serialization protocol between the AnyEvent::DBI server process and
199 your program does not support the passage of closures.
200
201 Here's an example to extend the query language in SQLite so it
202 supports an intstr() function:
203
204 $cv = AnyEvent->condvar;
205 $dbh->func (
206 q{
207 instr => 2, sub {
208 my ($string, $search) = @_;
209 return index $string, $search;
210 },
211 }, 90 },
212 create_function => sub { 91 trace => 1; # or verbose => 1, for less output
213 return $cv->send ($@) 92
214 unless $#_; 93 exec => $path (default: "gdb")
215 $cv->send (undef, @_[1,2,3]); 94 The path of the GDB executable.
216 } 95
96 args => [$string...] (default: ["-n"])
97 An optional array of parameters to pass to GDB. This should not
98 be used to load a program executable, use the
99 "file_exec_and_symbols", "target_attach" or similar MI commands
100 instead.
101
102 trace => $boolean (default: 0)
103 If true, then all commands sent to GDB are printed to STDOUT
104 prefixed with "> ", and all replies received from GDB are
105 printed to STDOUT prefixed with "< ".
106
107 verbose => $boolean (default: true if trace is enabled, false
108 otherwise)
109 If true, then log output and possibly other information is
110 printed to STDOUT.
111
112 on_xxxx => $callback->(...)
113 This specifies a callback for a specific event - see the EVENTS
114 section later in this document.
115
116 $gdb->cmd_raw ($command, $cb->($class, $results, $console))
117 Execute a raw command: $command is sent unchanged to GDB. See "cmd_"
118 for a description of the callback arguments.
119
120 Example: execute a CLI command and print its output.
121
122 $gdb->cmd_raw ("info sh", sub {
123 print "$_[3]\n";
217 ); 124 });
218 125
219 my ($err,$rc,$errcode,$errstr) = $cv->recv; 126 $gdb->cmd ($command => [$option...], $parameter..., $cb->($class,
127 $results, $console))
128 Execute a MI command and invoke the callback with the results.
220 129
221 die $err if defined $err; 130 $command is a MI command name. The leading minus sign can be
222 die "EVAL failed: $errstr" 131 omitted, and instead of minus signs, you can use underscores, i.e.
223 if $errcode; 132 all the following command names are equivalent:
224 133
225 # otherwise, we can ignore $rc and $errcode for this particular func 134 "-break-insert" # as documented in the GDB manual
135 -break_insert # using underscores and _ to avoid having to quote
136 break_insert # ditto, when e.g. used to the left of a =>
137 "break-insert" # no leading minus
138
139 The second argument is an optional array reference with options
140 (i.e. it can simply be missing). Each $option is either an option
141 name (similar rules as with command names, i.e. no initial "--") or
142 an array reference with the first element being the option name, and
143 the remaining elements being parameters: [$option, $parameter...].
144
145 The remaining arguments, excluding the last one, are simply the
146 parameters passed to GDB.
147
148 All options and parameters will be properly quoted.
149
150 When the command is done, the callback $cb will be invoked with
151 $class being one of "done", "connected", "error" or "exit" (note:
152 not "running"), $results being a has reference with all the
153 "variable=value" pairs from the result list.
154
155 $console is an array reference with all the GDB console messages
156 written while command executes (for MI commands, this should always
157 be "undef" and can be ignored).
158
159 Example: #todo#
160
161 ($results, $console) = $gdb->cmd_sync ($command => [$option...],
162 $parameter...]) =item $results = $gdb->cmd_sync ($command =>
163 [$option...], $parameter...])
164 Like "cmd", but blocks execution until the command has been
165 executed, and returns the results if sucessful. Croaks when GDB
166 returns with an error.
167
168 This is purely a convenience method for small scripts: since it
169 blocks execution using a condvar, it is not suitable to be used
170 inside callbacks or modules.
171
172 That is, unless Coro is used - with Coro, you can run multiple
173 "cmd_sync" methods concurrently form multiple threads, with no
174 issues.
175
176 EVENTS
177 AnyEvent::GDB is asynchronous in nature, as the goal of the MI interface
178 is to be fully asynchronous. Due to this, a user of this interface must
179 be prepared to handle various events.
180
181 When an event is produced, the GDB object will look for the following
182 four handlers and, if found, will call each one in order with the GDB
183 object and event name (without "on_") as the first two arguments,
184 followed by any event-specific arguments:
185
186 on_event method on the GDB object
187 Useful when subclassing.
188
189 on_event constructor parameter/object member
190 The callback specified as "on_event" parameter to the constructor.
191
192 on_EVENTNAME method on the GDB object
193 Again, mainly useful when subclassing.
194
195 on_EVENTNAME constructor parameter/object member
196 Any callback specified as "on_EVENTNAME" parameter to the
197 constructor.
198
199 You can change callbacks dynamically by simply replacing the
200 corresponding "on_XXX" member in the $gdb object:
201
202 $gdb->{on_event} = sub {
203 # new event handler
204 };
205
206 Here's the list of events with a description of their arguments.
207
208 on_eof => $cb->($gdb, "eof")
209 Called whenever GDB closes the connection. After this event, the
210 object is partially destroyed and must not be accessed again.
211
212 on_target => $cb->($gdb, "target", $string)
213 Output received from the target. Normally, this is sent directly to
214 STDOUT by GDB, but remote targets use this hook.
215
216 on_log => $cb->($gdb, "log", $string)
217 Log output from GDB. Best printed to STDOUT in interactive sessions.
218
219 on_TYPE => $cb->($gdb, "TYPE", $class, $results)
220 Called for GDB "exec", "status" and "notify" event (TYPE is one of
221 these three strings). $class is the class of the event, with "-"
222 replaced by "_" everywhere.
223
224 For each of these, the GDB object will create *two* events: one for
225 TYPE, and one for TYPE_CLASS. Usuaully you should provide the more
226 specific event (TYPE_CLASS).
227
228 on_TYPE_CLASS => $cb->($gdb, "TYPE_CLASS", $results)
229 Called for GDB "exec", "status" and "notify" event: TYPE is one of
230 these three strings, the class of the event (with "-" replaced b
231 "_"s) is appended to it to form the TYPE_CLASS (e.g. "exec_stopped"
232 or "notify_library_loaded").
233
234 STATUS STORAGE
235 The default implementations of the event method store the thread,
236 thread_group, recording, library and running status insid ethe $gdb
237 object.
238
239 You can access these at any time. Specifically, the following
240 information is available:
241
242 "$gdb->{thread_group}{*id*}"
243 The "thread_group" member stores a hash for each existing thread
244 group. The hash always contains the "id" member, but might also
245 contain other members.
246
247 "$gdb->{thread_group}{*id*}{pid}"
248 The "pid" member only exists while the thread group is running a
249 program, and contaisn the PID of the program.
250
251 "$gdb->{thread_group}{*id*}{exit_code}"
252 The "exit_code" member only exists after a program has finished
253 executing, and before it is started again, and contains the exit
254 code of the program.
255
256 "$gdb->{thread_group}{*id*}{recording}"
257 The "recording" member only exists if recording has been previously
258 started, and is 1 if recoridng is currently active, and 0 if it has
259 been stopped again.
260
261 "$gdb->{thread}{*id*}"
262 The "thread" member stores a hash for each existing thread. The hash
263 always contains the "id" member with the thread id, and the
264 "group_id" member with the corresponding thread group id.
265
266 "$gdb->{thread}{*id*}{running}"
267 The "running" member is 1 while the thread is, well, running, and is
268 missing otherwise.
269
270 "$gdb->{thread}{*id*}{stopped}"
271 The "stopped" member contains the result list from the
272 "on_exec_stopped" notification that caused the thread to stop, and
273 only exists when the thread is topped.
274
275 "$gdb->{library}{*id*}"
276 The "library" member contains all results from the
277 "on_library_loaded" event (such as "id", "target_name", "host_name"
278 and potentially a "thread_group".
226 279
227SEE ALSO 280SEE ALSO
228 AnyEvent, DBI, Coro::Mysql. 281 AnyEvent,
282 <http://sourceware.org/gdb/current/onlinedocs/gdb/GDB_002fMI.html#GDB_00
283 2fMI>.
229 284
230AUTHOR 285AUTHOR
231 Marc Lehmann <schmorp@schmorp.de> 286 Marc Lehmann <schmorp@schmorp.de>
232 http://home.schmorp.de/ 287 http://home.schmorp.de/
233 288
234 Adam Rosenstein <adam@redcondor.com>
235 http://www.redcondor.com/
236

Diff Legend

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