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

[Simon Marchi <simon dot marchi at polymtl dot ca>]

On 2017-09-09 08:55, Eli Zaretskii wrote:
> > From: Tom Tromey <tom@tromey.com>
> > Cc: Tom Tromey <tom@tromey.com>
> > Date: Fri,  8 Sep 2017 18:33:51 -0600
> >
> > This adds a few new events to gdb's Python layer: new_inferior,
> > inferior_deleted, and new_thread.  I wanted to be able to add a
> > combined inferior/thread display window to my GUI, and I needed a few
> > events to make this work.  This is PR python/15622.
> >
> > gdb/ChangeLog
> > 2017-09-08  Tom Tromey  <tom@tromey.com>
> >
> > 	PR python/15622:
> > 	* NEWS: Add entry.
> > 	* python/python.c (do_start_initialization): Initialize new event
> > 	types.
> > 	* python/python-internal.h (gdbpy_initialize_new_inferior_event)
> > 	(gdbpy_initialize_inferior_deleted_event)
> > 	(gdbpy_initialize_new_thread_event): Declare.
> > 	* python/py-threadevent.c (create_thread_event_object): Add option
> > 	"thread" parameter.
> > 	* python/py-inferior.c (new_thread_event_object_type)
> > 	(new_inferior_event_object_type)
> > 	(inferior_deleted_event_object_type): Declare.
> > 	(python_new_inferior, python_inferior_deleted): New functions.
> > 	(add_thread_object): Emit new_thread event.
> > 	(gdbpy_initialize_inferior): Attach new functions to corresponding
> > 	observers.
> > 	(new_thread, new_inferior, inferior_deleted): Define new event
> > 	types.
> > 	* python/py-evts.c (gdbpy_initialize_py_events): Add new
> > 	registries.
> > 	* python/py-events.h (events_object) <new_inferior,
> > 	inferior_deleted, new_thread>: New fields.
> > 	* python/py-event.h (create_thread_event_breakpoint): Add optional
> > 	"thread" parameter.
> >
> > gdb/doc/ChangeLog
> > 2017-09-08  Tom Tromey  <tom@tromey.com>
> >
> > 	* python.texi (Events In Python): Document new events.
> >
> > gdb/testsuite/ChangeLog
> > 2017-09-08  Tom Tromey  <tom@tromey.com>
> >
> > 	* gdb.python/py-infthread.exp: Add tests for new_thread event.
> > 	* gdb.python/py-inferior.exp: Add tests for new inferior events.
>
> OK for the documentation parts.
>
> Thanks.

I find the resulting documentation page about Python Events a bit hard 
to follow.  The "events.new_thread" event registry refers to the 
gdb.ThreadEvent type, which itself is defined under the "events.cont" 
registry.  There it says that inferior_thread is always not None in 
none-stop, and always None in all-stop.  That is contradictory with the 
text under "events.new_thread".  If it is possible for event types to be 
emitted by different event registries, I think they should be documented 
separately (on the same page, but in two sections).

Simon