From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 2126) id E97BF3856DEE; Thu, 14 Apr 2022 15:52:59 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org E97BF3856DEE Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable From: Tom Tromey To: gdb-cvs@sourceware.org Subject: [binutils-gdb] Reorganize Python events documentation X-Act-Checkin: binutils-gdb X-Git-Author: Tom Tromey X-Git-Refname: refs/heads/master X-Git-Oldrev: df4397e378fa6813301e80c08fd1358aa07697df X-Git-Newrev: 77d97a0a19033a45fc7e691078c90718f9f5d5e5 Message-Id: <20220414155259.E97BF3856DEE@sourceware.org> Date: Thu, 14 Apr 2022 15:52:59 +0000 (GMT) X-BeenThere: gdb-cvs@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gdb-cvs mailing list List-Unsubscribe: , List-Archive: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 14 Apr 2022 15:53:00 -0000 https://sourceware.org/git/gitweb.cgi?p=3Dbinutils-gdb.git;h=3D77d97a0a1903= 3a45fc7e691078c90718f9f5d5e5 commit 77d97a0a19033a45fc7e691078c90718f9f5d5e5 Author: Tom Tromey Date: Fri Feb 25 11:33:32 2022 -0700 Reorganize Python events documentation =20 This slightly reorganizes the Python events documentation. It hoists the "ThreadEvent" text out of the list of events, where it seemed to be misplaced. It tidies the formatting a little bit (adding some vertical space for easier reading in info), fixes a typo, adds some missing commas, and fixes an incorrect reference to NewInferiorEvent. Diff: --- gdb/doc/python.texi | 62 ++++++++++++++++++++++++++++---------------------= ---- 1 file changed, 33 insertions(+), 29 deletions(-) diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 7c414b01d70..cb5283e03c0 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -3367,56 +3367,58 @@ of type @code{gdb.ExitedEvent}. As you can see in = the example the @code{ExitedEvent} object has an attribute which indicates the exit code of the inferior. =20 -The following is a listing of the event registries that are available and -details of the events they emit: - -@table @code - -@item events.cont -Emits @code{gdb.ThreadEvent}. - -Some events can be thread specific when @value{GDBN} is running in non-stop -mode. When represented in Python, these events all extend -@code{gdb.ThreadEvent}. Note, this event is not emitted directly; instead, -events which are emitted by this or other modules might extend this event. -Examples of these events are @code{gdb.BreakpointEvent} and -@code{gdb.ContinueEvent}. +Some events can be thread specific when @value{GDBN} is running in +non-stop mode. When represented in Python, these events all extend +@code{gdb.ThreadEvent}. This event is a base class and is never +emitted directly; instead, events which are emitted by this or other +modules might extend this event. Examples of these events are +@code{gdb.BreakpointEvent} and @code{gdb.ContinueEvent}. +@code{gdb.ThreadEvent} holds the following attributes: =20 @defvar ThreadEvent.inferior_thread In non-stop mode this attribute will be set to the specific thread which w= as involved in the emitted event. Otherwise, it will be set to @code{None}. @end defvar =20 -Emits @code{gdb.ContinueEvent} which extends @code{gdb.ThreadEvent}. +The following is a listing of the event registries that are available and +details of the events they emit: =20 -This event indicates that the inferior has been continued after a stop. For -inherited attribute refer to @code{gdb.ThreadEvent} above. +@table @code + +@item events.cont +Emits @code{gdb.ContinueEvent}, which extends @code{gdb.ThreadEvent}. +This event indicates that the inferior has been continued after a +stop. For inherited attribute refer to @code{gdb.ThreadEvent} above. =20 @item events.exited -Emits @code{events.ExitedEvent} which indicates that the inferior has exit= ed. -@code{events.ExitedEvent} has two attributes: +Emits @code{events.ExitedEvent}, which indicates that the inferior has +exited. @code{events.ExitedEvent} has two attributes: + @defvar ExitedEvent.exit_code An integer representing the exit code, if available, which the inferior=20 has returned. (The exit code could be unavailable if, for example, @value{GDBN} detaches from the inferior.) If the exit code is unavailable, the attribute does not exist. @end defvar + @defvar ExitedEvent.inferior A reference to the inferior which triggered the @code{exited} event. @end defvar =20 @item events.stop -Emits @code{gdb.StopEvent} which extends @code{gdb.ThreadEvent}. +Emits @code{gdb.StopEvent}, which extends @code{gdb.ThreadEvent}. =20 -Indicates that the inferior has stopped. All events emitted by this regis= try -extend StopEvent. As a child of @code{gdb.ThreadEvent}, @code{gdb.StopEve= nt} -will indicate the stopped thread when @value{GDBN} is running in non-stop -mode. Refer to @code{gdb.ThreadEvent} above for more details. +Indicates that the inferior has stopped. All events emitted by this +registry extend @code{gdb.StopEvent}. As a child of +@code{gdb.ThreadEvent}, @code{gdb.StopEvent} will indicate the stopped +thread when @value{GDBN} is running in non-stop mode. Refer to +@code{gdb.ThreadEvent} above for more details. =20 -Emits @code{gdb.SignalEvent} which extends @code{gdb.StopEvent}. +Emits @code{gdb.SignalEvent}, which extends @code{gdb.StopEvent}. =20 -This event indicates that the inferior or one of its threads has received = as -signal. @code{gdb.SignalEvent} has the following attributes: +This event indicates that the inferior or one of its threads has +received a signal. @code{gdb.SignalEvent} has the following +attributes: =20 @defvar SignalEvent.stop_signal A string representing the signal received by the inferior. A list of poss= ible @@ -3424,7 +3426,8 @@ signal values can be obtained by running the command = @code{info signals} in the @value{GDBN} command prompt. @end defvar =20 -Also emits @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}. +Also emits @code{gdb.BreakpointEvent}, which extends +@code{gdb.StopEvent}. =20 @code{gdb.BreakpointEvent} event indicates that one or more breakpoints ha= ve been hit, and has the following attributes: @@ -3434,6 +3437,7 @@ A sequence containing references to all the breakpoin= ts (type @code{gdb.Breakpoint}) that were hit. @xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} obj= ect. @end defvar + @defvar BreakpointEvent.breakpoint A reference to the first breakpoint that was hit. This function is maintained for backward compatibility and is now deprecat= ed=20 @@ -3555,7 +3559,7 @@ is removed, say via @code{remove-inferiors}. The event is of type @code{gdb.InferiorDeletedEvent}. This has a single attribute: =20 -@defvar NewInferiorEvent.inferior +@defvar InferiorDeletedEvent.inferior The inferior that is being removed, a @code{gdb.Inferior} object. @end defvar