Re: [PATCH] stepi/nexti: skip signal handler if "handle nostop" signal arrives

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Sat, 25 Oct 2014 15:00:40 +0100
> From: Pedro Alves <palves@redhat.com>
> CC: gdb-patches@sourceware.org
> 
> >>> It might be the simplest to separate the two issues, and describe each
> >>> one on its own.
> >>
> >> I'll give that a try.
> > 
> > Thanks.  Let me know if I can help.
> 
> Alright, here's a new, expanded version.
> 
> Let me know what you think.

Thanks, this is a huge improvement.  I have only a couple of minor
stylistic suggestions:

> +@cindex stepping and signal handlers
> +@anchor{stepping and signal handlers}
> +
> +@value{GDBN} optimizes for stepping the mainline code.  If a signal
> +that has @code{handle nostop} and @code{handle pass} set arrives while
> +a stepping command (e.g., @code{stepi}, @code{step}, @code{next}) is
> +in progress, @value{GDBN} lets the signal handler run and then resumes
> +stepping the mainline code once the signal handler returns.  In other
> +words, @value{GDBN} steps over the signal handler.  If the signal has
> +@code{handle noprint} set, then you won't even hear about it.  This
> +prevents signals that you've specified as not interesting (with

I would suggest to use a semi-colon, not a period, before the last
"This".  That's because the last sentence is logically an immediate
continuation of the one before it.  By putting a full stop between
them we create a potential for misunderstanding to what "this" refers,
since the previous text described 2 different situations.  Using a
semi-colon removes that danger.

For the same reason, it might be better to make "If the signal has
'handle noprint' ..." start a new paragraph.

> +@cindex stepping into signal handlers
> +@anchor{stepping into signal handlers}

I would remove this @cindex entry: it doesn't add anything useful to
the previous one, and will likely point to the same page.

> +If the program was stopped for a signal (that is, stopped before the
> +program sees it), due to @code{handle stop} being set, and
> +@code{handle pass} is in effect for that signal too, and your program
> +handles the signal, a stepping command such as for example
> +@code{stepi} or @code{step} steps @emph{into} the signal's handler (if
> +the target supports it).

This is a mouthful, not in the least because of excessive use of past
tense.  How about this variant instead:

  If you set @code{handle stop} for a signal, @value{GDBN} stops your
  program and announces the signal when it arrives, before the program
  sees it.  If you also set @code{handle pass} for that signal, and
  your program sets up a handler for it, then issuing a stepping
  command, such as @code{step} or @code{stepi}, when your program is
  stopped due to the signal will step @emph{into} the signal handler
  (if the target supports that).

> +Likewise, if the @code{queue-signal} command was used to queue a
> +signal to be delivered to the current thread when execution of the

Please reword in active tens ("... if you use the @code{queue-signal}
command to queue ...").

> +thread resumes (@pxref{Signaling, ,Giving your Program a Signal}),
> +then a stepping command steps into the signal's handler.

Not sure I understand the sequence here.  First, I queue-signal, then
the signal is delivered and the thread stops, and _then_ I issue si?
I guess the "when execution of the thread resumes" confused me.

Thanks.