Re: [RFA 1/3] Add new_inferior, inferior_deleted, and new_thread events

Simon Marchi
2017-09-10T19:37:39Z

On 2017-09-10 02:21, Tom Tromey wrote:
>>>>>> "Simon" == Simon Marchi <simon.marchi@polymtl.ca> writes:
>
> Simon> I find the resulting documentation page about Python Events a
> bit hard
> Simon> to follow. The "events.new_thread" event registry refers to the
> Simon> gdb.ThreadEvent type, which itself is defined under the
> "events.cont"
> Simon> registry. There it says that inferior_thread is always not None
> in
> Simon> none-stop, and always None in all-stop. That is contradictory
> with
> Simon> the text under "events.new_thread". If it is possible for event
> types
> Simon> to be emitted by different event registries, I think they should
> be
> Simon> documented separately (on the same page, but in two sections).
>
> How about this doc patch instead?

That's fine with me, I think it makes it clear enough that the comments
about the inferior_thread field under events.cont don't apply here.

> diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
> index 32d7939..1e96dbc 100644
> --- a/gdb/doc/python.texi
> +++ b/gdb/doc/python.texi
> @@ -2989,6 +2989,39 @@ invalid state; that is, the @code{is_valid}
> method will return
> This event carries no payload. It is emitted each time @value{GDBN}
> presents a prompt to the user.
>
> +@item events.new_inferior
> +This is notified when a new inferior is created. Note that the
> +inferior is not necessarily running; in fact, it may not even have an
> +associated executable.
> +
> +The event is of type @code{gdb.NewInferiorEvent}. This has a single
> +attribute:
> +
> +@defvar NewInferiorEvent.inferior
> +The new inferior, a @code{gdb.Inferior} object.
> +@end defvar
> +
> +@item events.inferior_deleted
> +This is notified when an inferior has been deleted. Note that this is
> +not the same as process exit; it is notified when the inferior itself
> +is removed, say via @code{remove-inferiors}.
> +
> +The event is of type @code{gdb.InferiorDeletedEvent}. This has a
> single
> +attribute:
> +
> +@defvar NewInferiorEvent.inferior
> +The inferior that is being removed, a @code{gdb.Inferior} object.
> +@end defvar
> +
> +@item events.new_thread
> +This emitted when @value{GDBN} notices a new thread. The event is of

"This emitted". I also noticed that for other events you used "This is
notified". Perhaps it would be better to stick with "This is emitted"
everywhere to be consistent.

If Eli is fine with this version of the doc, I think this patch is ready
to go in.

Thanks,

Simon