view release on metacpan or  search on metacpan

GDB.pm  view on Meta::CPAN

All options and parameters will be properly quoted.

When the command is done, the callback C<$cb> will be invoked with
C<$class> being one of C<done>, C<connected>, C<error> or C<exit>
(note: not C<running>), C<$results> being a has reference with all the
C<variable=value> pairs from the result list.

C<$console> is an array reference with all the GDB console messages
written while command executes (for MI commands, this should always be
C<undef> and can be ignored).

Example: #todo#

=cut

sub cmd {
   my $cb = pop;
   my ($self, $cmd, @arg) = @_;

   $cmd =~ s/^[\-_]?/_/;
   $cmd =~ y/_/-/;

   $cmd .= " ";

   my $opt = ref $arg[0] ? shift @arg : [];

   for (@$opt) {
      $cmd .= "-";
      $cmd .= (_q $_) . " "
         for (ref) ? @$_ : $_;
   }

   # the MI syntax is inconsistent, providing "--" in case
   # parameters start with "-", but not allowing "-" as first
   # char of a parameter. in fact, "--" is flagged as unknown
   # option.
   if (@arg) {
#      $cmd .= "-- ";

      $cmd .= (_q $_) . " "
         for @arg;
   }

   # remove trailing " "
   substr $cmd, -1, 1, "";

   $self->cmd_raw ($cmd, $cb);
}

=item ($results, $console) = $gdb->cmd_sync ($command => [$option...], $parameter...])
=item $results = $gdb->cmd_sync ($command => [$option...], $parameter...])

Like C<cmd>, but blocks execution until the command has been executed, and
returns the results if sucessful. Croaks when GDB returns with an error.

This is purely a convenience method for small scripts: since it blocks
execution using a condvar, it is not suitable to be used inside callbacks
or modules.

That is, unless L<Coro> is used - with Coro, you can run multiple
C<cmd_sync> methods concurrently form multiple threads, with no issues.

=cut

sub cmd_sync {
   push @_, my $cv = AE::cv;
   &cmd;

   my ($class, $results, $console) = $cv->recv;

   Carp::croak $results->{msg}
      if $class eq "error";

   wantarray ? ($results, $console) : $results
}

sub event {
   my ($self, $event, @args) = @_;

#   if ($self->{verbose}) {
#      use Data::Dumper;
#      print Data::Dumper
#            ->new ([[$event, @args]])
#            ->Pair ("=>")
#            ->Useqq (1)
#            ->Indent (0)
#            ->Terse (1)
#            ->Quotekeys (0)
#            ->Sortkeys (1)
#            ->Dump,
#            "\n";
#   }

   my $cb;

   $cb = $self->can ("on_event")  and $cb->($self, $event, @args);
   $cb = $self->    {on_event}    and $cb->($self, $event, @args);
   $cb = $self->can ("on_$event") and $cb->($self, $event, @args);
   $cb = $self->    {"on_$event"} and $cb->($self, $event, @args);
}

# predefined events

sub on_notify_thread_group_added {
   my ($self, undef, $r) = @_;

   $self->{thread_group}{$r->{id}} = $r;
}

sub on_notify_thread_group_removed {
   my ($self, undef, $r) = @_;

   delete $self->{thread_group}{$r->{id}};
}

sub on_notify_thread_group_started {
   my ($self, undef, $r) = @_;

   delete $self->{thread_group}{exit_code};
   $self->{thread_group}{$r->{id}}{pid} = $r->{pid};
}

sub on_notify_thread_group_exited {
   my ($self, undef, $r) = @_;

   delete $self->{thread_group}{pid};
   $self->{thread_group}{$r->{id}}{exit_code} = $r->{exit_code};
}

sub on_notify_record_started {
   my ($self, undef, $r) = @_;

   $self->{thread_group}{$r->{id}}{recording} = 1;
}

sub on_notify_record_stopped {
   my ($self, undef, $r) = @_;

   $self->{thread_group}{$r->{id}}{recording} = 0;
}

sub on_notify_thread_created {
   my ($self, undef, $r) = @_;

   $self->{thread}{$r->{id}} = $r;
}

sub on_notify_thread_exited {
   my ($self, undef, $r) = @_;

   delete $self->{thread}{$r->{id}};
}

sub _threads {
   my ($self, $id) = @_;

   ref $id
      ? @{ $self->{thread} }{@$id}
      : $id eq "all"
         ? values %{ $self->{thread} }
         : $self->{thread}{$id}
}

sub on_exec_running {
   my ($self, undef, $r) = @_;

   for ($self->_threads ($r->{thread_id})) {
      delete $_->{stopped};
      $_->{running} = 1;
   }
}

sub on_exec_stopped {
   my ($self, undef, $r) = @_;

   for ($self->_threads ($r->{stopped_threads})) {
      delete $_->{running};
      $_->{stopped} = $r;
   }

#   $self->event ("thread_$r->{reason}" => $r, [map $_->{id}, $self->_threads ($r)]);
}

sub _thread_groups {
   my ($self, $r) = @_;

   exists $r->{thread_group}
      ? $self->{thread_group}{$r->{thread_group}}
      : values %{ $self->{thread_group} }
}

sub on_notify_library_loaded {
   my ($self, undef, $r) = @_;

   $_->{library}{$r->{id}} = $r
      for $self->_thread_groups ($r);
}

sub on_notify_library_unloaded {
   my ($self, undef, $r) = @_;

   delete $_->{library}{$r->{id}}
      for $self->_thread_groups ($r);
}

=back

=head2 EVENTS

AnyEvent::GDB is asynchronous in nature, as the goal of the MI interface
is to be fully asynchronous. Due to this, a user of this interface must
be prepared to handle various events.

When an event is produced, the GDB object will look for the following four
handlers and, if found, will call each one in order with the GDB object
and event name (without C<on_>) as the first two arguments, followed by
any event-specific arguments:

=over 4

=item on_event method on the GDB object

Useful when subclassing.

=item on_event constructor parameter/object member

The callback specified as C<on_event> parameter to the constructor.

=item on_EVENTNAME method on the GDB object

Again, mainly useful when subclassing.

=item on_EVENTNAME constructor parameter/object member

Any callback specified as C<on_EVENTNAME> parameter to the constructor.

=back

You can change callbacks dynamically by simply replacing the corresponding
C<on_XXX> member in the C<$gdb> object:

   $gdb->{on_event} = sub {
      # new event handler
   };

Here's the list of events with a description of their arguments.

=over 4

=item on_eof => $cb->($gdb, "eof")

Called whenever GDB closes the connection. After this event, the object is
partially destroyed and must not be accessed again.

=item on_target => $cb->($gdb, "target", $string)

Output received from the target. Normally, this is sent directly to STDOUT
by GDB, but remote targets use this hook.

=item on_log => $cb->($gdb, "log", $string)

Log output from GDB. Best printed to STDOUT in interactive sessions.

=item on_TYPE => $cb->($gdb, "TYPE", $class, $results)

Called for GDB C<exec>, C<status> and C<notify> event (TYPE is one of
these three strings). C<$class> is the class of the event, with C<->
replaced by C<_> everywhere.

For each of these, the GDB object will create I<two> events: one for TYPE,
and one for TYPE_CLASS. Usuaully you should provide the more specific
event (TYPE_CLASS).

=item on_TYPE_CLASS => $cb->($gdb, "TYPE_CLASS", $results)

Called for GDB C<exec>, C<status> and C<notify> event: TYPE is one
of these three strings, the class of the event (with C<-> replaced b
C<_>s) is appended to it to form the TYPE_CLASS (e.g. C<exec_stopped> or
C<notify_library_loaded>).

=back

=head2 STATUS STORAGE

The default implementations of the event method store the thread,
thread_group, recording, library and running status insid ethe C<$gdb>
object.

You can access these at any time. Specifically, the following information
is available:

=over 4

=item C<< $gdb->{thread_group}{I<id>} >>

The C<thread_group> member stores a hash for each existing thread
group. The hash always contains the C<id> member, but might also contain
other members.

=item C<< $gdb->{thread_group}{I<id>}{pid} >>

The C<pid> member only exists while the thread group is running a program,
and contaisn the PID of the program.

=item C<< $gdb->{thread_group}{I<id>}{exit_code} >>

The C<exit_code> member only exists after a program has finished
executing, and before it is started again, and contains the exit code of
the program.

=item C<< $gdb->{thread_group}{I<id>}{recording} >>

The C<recording> member only exists if recording has been previously
started, and is C<1> if recoridng is currently active, and C<0> if it has
been stopped again.

=item C<< $gdb->{thread}{I<id>} >>

The C<thread> member stores a hash for each existing thread. The hash
always contains the C<id> member with the thread id, and the C<group_id>
member with the corresponding thread group id.

=item C<< $gdb->{thread}{I<id>}{running} >>

The C<running> member is C<1> while the thread is, well, running, and is
missing otherwise.

=item C<< $gdb->{thread}{I<id>}{stopped} >>

The C<stopped> member contains the result list from the C<on_exec_stopped>
notification that caused the thread to stop, and only exists when the
thread is topped.

=item C<< $gdb->{library}{I<id>} >>

The C<library> member contains all results from the C<on_library_loaded>
event (such as C<id>, C<target_name>, C<host_name> and potentially a
C<thread_group>.

=back

=head1 SEE ALSO

L<AnyEvent>, L<http://sourceware.org/gdb/current/onlinedocs/gdb/GDB_002fMI.html#GDB_002fMI>.

=head1 AUTHOR

   Marc Lehmann <schmorp@schmorp.de>
   http://home.schmorp.de/

=cut

1