Re: [patch] Support inferior events in python

Eli Zaretskii
2011-02-03T18:26:34Z

> 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.