Re: [patch] Support inferior events in python

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Thu, 03 Feb 2011 11:40:42 -0500
> From: sami wagiaalla <swagiaal@redhat.com>
> CC: gdb-patches@sourceware.org
> 
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -40,6 +40,14 @@
>  
>    ** gdb.parameter("directories") is now available.
>  
> +  ** Python Support for Inferior events.
> +     Python scripts can add observers to be notified of events
> +     occurring the in process being debugged.
> +     The following events are currently supported:
> +     - gdb.events.cont Continue event.
> +     - gdb.events.exited Inferior exited event.
> +     - gdb.events.stop Signal received, and Breakpoint hit events.
> +

OK for this part.

> +* Events In Python::            Listening for events from GDB.
                                                             ^^^
"@value{GDBN}" instead of a literal "GDB".

> +GDB provides a general event facility so that Python code can be
   ^^^
Ditto.

> +In order to be notified of an event, you must register an event handler
> +with an event registry.  An @dfn{event registry} is an object in the
           ^^^^^^^^^^^^^^      ^^^^^^^^^^^^^^^^^^^^
Please use @dfn when you first use the new term.  In this case, in the
previous sentence.

> +@defmethod EventRegistry connect callable
> +Add the given callable object to the registry.  This object will be called
> +when an event corresponding to this registry occurs.

"callable" should have the @var markup.

> +@defmethod EventRegistry disconnect callable
> +Remove the given object from the registry.  Once removed the object will no
                                                          ^^^
Same here.  And please add the missing comma after "removed".

Also, isn't it better to use "object" as the argument instead of
"callable"?  How about this:

  @defmethod EventRegistry connect object
  Add the given callable @var{object} to the registry.  This object will
  be called when an event corresponding to this registry occurs.
  @end defmethod

> +registry @code{events.exited}.  Once connected @code{exit_handler} receives
                                                ^^
A missing comma.

> +notifications of exited events.  The argument @dfn{event} in this example is

Hmm... "receives notifications" is not really true, is it?  It gets
called when exit events happen, right?

> +@item events.cont
> +Emits @code{gdb.ThreadEvent}

Please add a period at the end of this sentence.

> +Some events can be thread specific when GDB is running in non-stop mode.  When
                                           ^^^
"@value{GDBN}"

> +represented in python these events all extend @code{gdb.ThreadEvent}.  Note,
                  ^^^^^^
Should be "Python", right?  And please add a comma after it.

> +Emits @code{gdb.ContinueEvent} which extends @code{gdb.ThreadEvent}

A period at the end, please.

> +Emits @code{gdb.StopEvent} which extends @code{gdb.ThreadEvent}

Likewise.

> +Indicates that the inferior has stopped. All events emitted by this registry
> +extend StopEvent. As a child of @code{gdb.ThreadEvent} @code{gdb.StopEvent}
> +will indicate the stopped thread when gdb is running in non-stop mode. Refer
> +to @code{gdb.ThreadEvent} above for more details.

This paragraph needs two spaces after each sentence, not one.

Also, a comma is missing here:

> +extend StopEvent. As a child of @code{gdb.ThreadEvent} @code{gdb.StopEvent}
                                                        ^^^
And you need to use "@value{GDBN}" again here:

> +will indicate the stopped thread when gdb is running in non-stop mode. Refer
                                         ^^^

> +Emits @code{gdb.SignalEvent} which extends @code{gdb.StopEvent}

Period.

> +Also emits  @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}

Period.

> +@end table

This "@end table" is misplaced, it should have been after this:

> +@table @code
> +@defivar SignalEvent stop_signal
> +A string representing the signal received by the inferior.  A list of possible
> +signal values can be obtained by running the command @code{info signals} in
> +the @value{GDBN} command prompt.
> +@end defivar

OK with those changes.

Thanks.