Revise etc/DEBUG documentation

Revise etc/DEBUG documentation

[Alain Schneble]

[-- Attachment #1: Type: text/plain, Size: 449 bytes --]

Hello

While studying how signals are handled in Emacs (both when run under a
POSIX system as well as MS-Windows) and also how GDB deals with them, I
thought it would be worth to revise the section 'Getting control to the
debugger' in etc/DEBUG to include some more information about how
signals can be used to interrupt Emacs debuggee and return control back
to GDB.

Would you mind installing this patch?  Any comments are welcome.

Thanks
Alain


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Revise etc/DEBUG --]
[-- Type: text/x-patch, Size: 7503 bytes --]

From 0c83a574a0b425b7dfd3effd0e0d6383227a2500 Mon Sep 17 00:00:00 2001
From: Alain Schneble <a.s@realize.ch>
Date: Sat, 3 Sep 2016 12:08:11 +0200
Subject: [PATCH] Revise DEBUG doc on how to get control to the debugger

* etc/DEBUG: Revise section 'Getting control to the
debugger'. Restructure exisiting content into subsections and add
further documentation related to how signals can be used to get control
back to the debugger.
---
 etc/DEBUG | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 93 insertions(+), 21 deletions(-)

diff --git a/etc/DEBUG b/etc/DEBUG
index 656e29a..e4390c0 100644
--- a/etc/DEBUG
+++ b/etc/DEBUG
@@ -190,45 +190,83 @@ kick in, provided that you run under GDB.
 
 ** Getting control to the debugger
 
+*** Breakpoints
+
+Setting a breakpoint is the usual way to configure a point in the
+program's execution thread where control will be returned to the
+debugger.  It is therefore wise to add breakpoints just after Emacs
+has been loaded into the debugger, but before it is actually run.
+
 'Fsignal' is a very useful place to put a breakpoint in.  All Lisp
 errors go through there.  If you are only interested in errors that
 would fire the debugger, breaking at 'maybe_call_debugger' is useful.
 
+'Fredraw_display' is another convenient function.  It is one that is
+rarely called and which you can invoke at will interactively with "M-x
+redraw-display RET".
+
+*** Signal interception
+
 It is useful, when debugging, to have a guaranteed way to return to
-the debugger at any time.  When using X, this is easy: type C-z at the
-window where Emacs is running under GDB, and it will stop Emacs just
-as it would stop any ordinary program.  When Emacs is running in a
-terminal, things are not so easy.
+the debugger at any time.  This allows adding or removing breakpoints
+or inspecting Emacs's state at an arbitrary point in time.
+
+GDB intercepts all signals sent to the debuggee (aka inferior) and
+gives control over what will happen with those: whether or not control
+is returned to GDB, a message is printed or if it shall be passed to
+the inferior when continuing execution.
 
-The src/.gdbinit file in the Emacs distribution arranges for SIGINT
-(C-g in Emacs) to be passed to Emacs and not give control back to GDB.
-On modern POSIX systems, you can override that with this command:
+The src/.gdbinit file in the Emacs distribution arranges for SIGINT to
+be passed to Emacs and not give control back to GDB.  This is
+especially useful for an Emacs debuggee running in a terminal, as it
+is configured to send a SIGINT as response to C-g keystroke.  On
+modern POSIX systems, you can override that with this command:
 
    handle SIGINT stop nopass
 
 After this 'handle' command, SIGINT will return control to GDB.  If
-you want the C-g to cause a QUIT within Emacs as well, omit the 'nopass'.
+you want this signal to cause a QUIT within Emacs running in a
+terminal as well, omit the 'nopass'.
+
+To list the configuration of all signals, use this command:
+
+   info signal
 
 A technique that can work when 'handle SIGINT' does not is to store
 the code for some character into the variable stop_character.  Thus,
 
     set stop_character = 29
 
-makes Control-] (decimal code 29) the stop character.
-Typing Control-] will cause immediate stop.  You cannot
-use the set command until the inferior process has been started.
-Put a breakpoint early in 'main', or suspend the Emacs,
-to get an opportunity to do the set command.
+makes Control-] (decimal code 29) the stop character.  Typing
+Control-] will cause a SIGTSTP to be sent to the Emacs debuggee
+itself.  You cannot use the set command until the inferior process has
+been started as it refers to a global variable in the Emacs debuggee
+process.  Put a breakpoint early in 'main', or suspend Emacs, to get
+an opportunity to do the set command.
+
+You can also send a signal to the inferior Emacs at any time by using
+kill.  For instance, to send a SIGTSTP, invoke the following command
+from a shell:
+
+   kill -TSTP [Inferior-Emacs-PID]
+
+Depending on the 'handle' configuration, this might also give control
+back to GDB.  If so, the signal can be suppressed from being forwarded
+to the inferior and Emacs resumed by invoking the command 'signal 0';
+regardeless of the active 'pass' / 'nopass' configuration. To
+substitute it with another signal, use 'signal [SIGNAME]' instead.
 
-Another technique for get control to the debugger is to put a
-breakpoint in some rarely used function.  One such convenient function
-is Fredraw_display, which you can invoke at will interactively with
-"M-x redraw-display RET".
+*** Emacs running in a terminal
 
-When Emacs is running in a terminal, it is sometimes useful to use a separate
-terminal for the debug session.  This can be done by starting Emacs as usual,
-then attaching to it from gdb with the 'attach' command which is explained in
-the node "Attach" of the GDB manual.
+When Emacs is running in a terminal, typing C-g will either send a
+SIGINT or a SIGQUIT signal to the Emacs process. And it arranges for
+both SIGINT and SIGQUIT to cause a QUIT within Emacs.
+
+It is sometimes useful to use a separate terminal for the debug
+session.  This can be done by starting Emacs as usual, then attaching
+to it from gdb with the 'attach' command which is explained in the
+node "Attach" of the GDB manual.  Another approach is shown under
+'Debugging the TTY (non-windowed) version' below.
 
 On MS-Windows, you can start Emacs in its own separate terminal by
 setting the new-console option before running Emacs under GDB:
@@ -236,6 +274,40 @@ setting the new-console option before running Emacs under GDB:
   (gdb) set new-console 1
   (gdb) run
 
+*** Emacs running under a window system
+
+When Emacs is running under a window system, reception of a SIGINT and
+SIGQUIT will cause it to terminate.  It might therefore be useful to
+configure the 'handle' command for those signals to use 'nopass', to
+prevent Emacs from terminating on reception of such signals.
+
+When using a window system, there is no reason for Emacs to handle C-g
+as a SIGINT, as keyboard input is processed by the window system's
+message pump.  Hence, no signal is sent as a response to a C-g.
+
+When using X, type C-z at the window where Emacs is running under GDB,
+and it will stop Emacs just as it would stop any ordinary program.
+
+On MS-Windows, starting Emacs in its own separate terminal even when
+running as a GUI application will allow you to send a Ctrl-c or
+Ctrl-Break to the console.  GDB treats them as a SIGINT, but Emacs
+won't terminate as it ignores these events.
+
+*** Signals sent to GDB
+
+There is a sublety in GDB about how it handles SIGINT signals sent to
+itself: it simply forwards them to the inferior process.  Hence,
+hitting C-c in the terminal used by GDB is a very convenient way to
+interrupt Emacs and -- depending on 'handle SIGINT' setup -- return
+control to the debugger.  When debugging with GDB in Emacs, you can
+use comint-interrupt-subjob command bound to 'C-c C-c' by default to
+get the same result.
+
+On MS-Windows, GDB will turn a C-c into a DebugBreakProcess call if
+Emacs is running in a separate terminal or it will just ignore it
+otherwise, as the event will be received by Emacs anyway when running
+under the same terminal as GDB.
+
 ** Examining Lisp object values.
 
 When you have a live process to debug, and it has not encountered a
-- 
2.9.1

Re: Revise etc/DEBUG documentation

[Eli Zaretskii]

> From: Alain Schneble <a.s@realize.ch>
> Date: Sat, 3 Sep 2016 12:31:56 +0200
> 
> While studying how signals are handled in Emacs (both when run under a
> POSIX system as well as MS-Windows) and also how GDB deals with them, I
> thought it would be worth to revise the section 'Getting control to the
> debugger' in etc/DEBUG to include some more information about how
> signals can be used to interrupt Emacs debuggee and return control back
> to GDB.
> 
> Would you mind installing this patch?  Any comments are welcome.

Thanks.

Frankly, I'm a bit confused after reading the changes.  Some of them
rephrase what was already in DEBUG, others rearrange existing text
(and also rephrase it a bit), still others describe features that I
either didn't understand or they will work only under specific
circumstances.  I guess I don't really understand the main idea behind
the proposed changes.

I also am not sure we should repeat here stuff that is basic GDB
usage.  Any such descriptions are bound to be incomplete and thus
inaccurate.  It is better to refer the readers to the GDB manual, if
they are not already proficient.

How about if we first add any missing information, and leave
rephrasing for a separate patch?  Or maybe just tell what you think is
missing in the current version, and let's take it from there.

Some specific comments and questions follow.

> +When Emacs is running under a window system, reception of a SIGINT and
> +SIGQUIT will cause it to terminate.  It might therefore be useful to
> +configure the 'handle' command for those signals to use 'nopass', to
> +prevent Emacs from terminating on reception of such signals.

I don't understand why is this useful.

> +When using a window system, there is no reason for Emacs to handle C-g
> +as a SIGINT, as keyboard input is processed by the window system's
> +message pump.  Hence, no signal is sent as a response to a C-g.

This explains how Emacs works, but I'm not sure it belongs in DEBUG.

> +When using X, type C-z at the window where Emacs is running under GDB,
> +and it will stop Emacs just as it would stop any ordinary program.

The "window where Emacs is running under GDB" part is IMO confusing: I
couldn't figure out what window does this refer to.  There might not
be such a window at all, AFAIU.

> +On MS-Windows, starting Emacs in its own separate terminal even when
> +running as a GUI application will allow you to send a Ctrl-c or
> +Ctrl-Break to the console.  GDB treats them as a SIGINT, but Emacs
> +won't terminate as it ignores these events.

This also left me confused.  First, what do you mean by "separate
terminal" in this case?  Up to here, when DEBUG says "terminal", it
means "text terminal", but here you are talking about GUI sessions, so
what is a "separate terminal" applicable to the GUI Emacs session on
MS-Windows?

Next, what do you mean by "send a Ctrl-c or +Ctrl-Break to the
console"?  What console is alluded to here?

Finally, what does the "GDB treats them as a SIGINT, but Emacs won't
terminate as it ignores these events" part want to tell?  I couldn't
figure that out.

> +On MS-Windows, GDB will turn a C-c into a DebugBreakProcess call if
> +Emacs is running in a separate terminal

Here's the "separate terminal" thing once again.

>                                          or it will just ignore it
> +otherwise, as the event will be received by Emacs anyway when running
> +under the same terminal as GDB.

This part is also confusing.  And I wonder why the signal-process
feature is not mentioned here.

Thanks again for working on this.

Re: Revise etc/DEBUG documentation

[Alain Schneble]

Eli Zaretskii <eliz@gnu.org> writes:

> Frankly, I'm a bit confused after reading the changes.  Some of them
> rephrase what was already in DEBUG, others rearrange existing text
> (and also rephrase it a bit), still others describe features that I
> either didn't understand or they will work only under specific
> circumstances.  I guess I don't really understand the main idea behind
> the proposed changes.

Thanks for reading my message. I was confused with how different the
behavior regarding signals is when debugging Emacs using GDB in all the
different variations (terminal/console, GUI, POSIX, MS-Windows).  Before
looking into Emacs and GDB sources in detail, I wasn't able to figure
out why it behaves differently.  That was the main idea behind the
proposed change.  To document these nuances.  Apparently, I missed the
point.  Sorry.

> I also am not sure we should repeat here stuff that is basic GDB
> usage.  Any such descriptions are bound to be incomplete and thus
> inaccurate.  It is better to refer the readers to the GDB manual, if
> they are not already proficient.

I basically agree.  But 1) there was already some information there and
2) some minimal hints really helps one (or at least me) to start off.
But it's probably hard to find a good boundary where to stop.  I guess
your point is that I passed it.

> How about if we first add any missing information, and leave
> rephrasing for a separate patch?  Or maybe just tell what you think is
> missing in the current version, and let's take it from there.

Actually, I tried this first but I had the impression that I start
mixing stuff that somehow does not belong together.  That's why I
started to restructure it.

> Some specific comments and questions follow.
>
>> +When Emacs is running under a window system, reception of a SIGINT and
>> +SIGQUIT will cause it to terminate.  It might therefore be useful to
>> +configure the 'handle' command for those signals to use 'nopass', to
>> +prevent Emacs from terminating on reception of such signals.
>
> I don't understand why is this useful.

Because it allows one to hit C-c in GDB, do some changes such as adding
breakpoints and then continue.  With 'pass' it would terminate Emacs if
it is run as a GUI application.  When run in a terminal, it does not
terminate.  A nuance.

>> +When using a window system, there is no reason for Emacs to handle C-g
>> +as a SIGINT, as keyboard input is processed by the window system's
>> +message pump.  Hence, no signal is sent as a response to a C-g.
>
> This explains how Emacs works, but I'm not sure it belongs in DEBUG.

True.  But I think such background information would have helped me a
lot.  I don't think that DEBUG should apriori not include any such
details that might help one to understand the interaction between the
User, Emacs and GDB.

>> +When using X, type C-z at the window where Emacs is running under GDB,
>> +and it will stop Emacs just as it would stop any ordinary program.
>
> The "window where Emacs is running under GDB" part is IMO confusing: I
> couldn't figure out what window does this refer to.  There might not
> be such a window at all, AFAIU.

To be honest, I don't understand this either.  But this was there
before.  I just took it over and rephrased it slightly.  For example C-z
in Gnome just minimizes the window (Emacs frame) AFAIK, but doesn't stop
Emacs.  Do you know what C-z usually does in X window with a GUI
application?  Does it send a signal to it?

>> +On MS-Windows, starting Emacs in its own separate terminal even when
>> +running as a GUI application will allow you to send a Ctrl-c or
>> +Ctrl-Break to the console.  GDB treats them as a SIGINT, but Emacs
>> +won't terminate as it ignores these events.
>
> This also left me confused.  First, what do you mean by "separate
> terminal" in this case?  Up to here, when DEBUG says "terminal", it
> means "text terminal", but here you are talking about GUI sessions, so
> what is a "separate terminal" applicable to the GUI Emacs session on
> MS-Windows?

separate terminal => set new-console 1.  I should have used the term
console rather than terminal here, I guess.

> Next, what do you mean by "send a Ctrl-c or +Ctrl-Break to the
> console"?  What console is alluded to here?

With new-console 1, when starting Emacs GUI, the console is visible as a
separate window in MS-Windows.  And it is this console window that can
be used to enter Ctrl-c or Ctrl-Break, even though we are running Emacs
as a GUI application.  A nuance.

> Finally, what does the "GDB treats them as a SIGINT, but Emacs won't
> terminate as it ignores these events" part want to tell?  I couldn't
> figure that out.
That it behaves differently than on POSIX, where a SIGINT would
terminate Emacs when running in "GUI mode".  A nuance.

>> +On MS-Windows, GDB will turn a C-c into a DebugBreakProcess call if
>> +Emacs is running in a separate terminal
>
> Here's the "separate terminal" thing once again.
Again, separate terminal => set new-console 1

>>                                          or it will just ignore it
>> +otherwise, as the event will be received by Emacs anyway when running
>> +under the same terminal as GDB.
>
> This part is also confusing.  And I wonder why the signal-process
> feature is not mentioned here.
All processes sharing the same console will receive the C-c event.  In
that case GDB doesn't have to escape to using DebugBreakProcess.  GDB
just ignores C-c and Emacs will receive it anyway.  This was another
thing that confused me.  That depenting on 'set new-console' setting,
GDB signals either a SIGINT (due to C-c being received by Emacs) or a
SIGTRAP (due to DebugBreakProcess) for the same initial C-c/SIGINT
event.  A nuance.

> Thanks again for working on this.

I hope I could clarify at least the intent of my change.  If you are
still confused, I'll restart and try what you proposed: To find a way to
only add missing information in the first place.  And to not rephrase
existing content.

Thanks for your input.  I appreciate it.

Re: Revise etc/DEBUG documentation

[Noam Postavsky]

On Sat, Sep 3, 2016 at 9:14 AM, Alain Schneble <a.s@realize.ch> wrote:
>>> +When using X, type C-z at the window where Emacs is running under GDB,
>>> +and it will stop Emacs just as it would stop any ordinary program.
>>
>> The "window where Emacs is running under GDB" part is IMO confusing: I
>> couldn't figure out what window does this refer to.  There might not
>> be such a window at all, AFAIU.
>
> To be honest, I don't understand this either.  But this was there
> before.  I just took it over and rephrased it slightly.  For example C-z
> in Gnome just minimizes the window (Emacs frame) AFAIK, but doesn't stop
> Emacs.  Do you know what C-z usually does in X window with a GUI
> application?  Does it send a signal to it?

There's no special meaning of C-z for X windows. Emacs binds it to
`suspend-frame'. The "window" in question here is the window of the
terminal emulator where gdb was started from. In this case hitting C-z
while Emacs is running gives back to the debugger (by sending SIGTSTP
apparently)

(gdb) run
Starting program: /home/npostavs/src/emacs/emacs-master/src/emacs -Q
[Thread debugging using libthread_db enabled]
Using host libthread_db library "/usr/lib/libthread_db.so.1".
[New Thread 0x7fffe959a700 (LWP 23870)]
[New Thread 0x7fffe8981700 (LWP 23871)]
[New Thread 0x7fffe3fff700 (LWP 23872)]
^Z
Thread 1 "emacs" received signal SIGTSTP, Stopped (user).
0x00007ffff0b1918c in pselect () from /usr/lib/libc.so.6
(gdb)

Re: Revise etc/DEBUG documentation

[Eli Zaretskii]

> From: Noam Postavsky <npostavs@users.sourceforge.net>
> Date: Sat, 3 Sep 2016 09:45:03 -0400
> Cc: Eli Zaretskii <eliz@gnu.org>, Emacs developers <emacs-devel@gnu.org>
> 
> There's no special meaning of C-z for X windows. Emacs binds it to
> `suspend-frame'. The "window" in question here is the window of the
> terminal emulator where gdb was started from. In this case hitting C-z
> while Emacs is running gives back to the debugger (by sending SIGTSTP
> apparently)

Right, I tried to clarify this in the changes I sent a minute ago.

Thanks.

Re: Revise etc/DEBUG documentation

[Alain Schneble]

Noam Postavsky <npostavs@users.sourceforge.net> writes:

> There's no special meaning of C-z for X windows. Emacs binds it to
> `suspend-frame'. The "window" in question here is the window of the
> terminal emulator where gdb was started from. In this case hitting C-z
> while Emacs is running gives back to the debugger (by sending SIGTSTP
> apparently)

Thank you.  Now I understand.  I though it referred to the Emacs window.
How could I miss it meant the terminal emulator where GDB was started
from...

> (gdb) run
> Starting program: /home/npostavs/src/emacs/emacs-master/src/emacs -Q
> [Thread debugging using libthread_db enabled]
> Using host libthread_db library "/usr/lib/libthread_db.so.1".
> [New Thread 0x7fffe959a700 (LWP 23870)]
> [New Thread 0x7fffe8981700 (LWP 23871)]
> [New Thread 0x7fffe3fff700 (LWP 23872)]
> ^Z
> Thread 1 "emacs" received signal SIGTSTP, Stopped (user).
> 0x00007ffff0b1918c in pselect () from /usr/lib/libc.so.6
> (gdb)

Re: Revise etc/DEBUG documentation

[Eli Zaretskii]

> From: Alain Schneble <a.s@realize.ch>
> Date: Sat, 3 Sep 2016 15:14:31 +0200
> Cc: emacs-devel@gnu.org
> 
> > I also am not sure we should repeat here stuff that is basic GDB
> > usage.  Any such descriptions are bound to be incomplete and thus
> > inaccurate.  It is better to refer the readers to the GDB manual, if
> > they are not already proficient.
> 
> I basically agree.  But 1) there was already some information there and
> 2) some minimal hints really helps one (or at least me) to start off.
> But it's probably hard to find a good boundary where to stop.  I guess
> your point is that I passed it.

I tried to find that boundary, see below.

In general, etc/DEBUG is supposed to be a cookbook-like collection of
tips, not a full-fledged manual.

> > How about if we first add any missing information, and leave
> > rephrasing for a separate patch?  Or maybe just tell what you think is
> > missing in the current version, and let's take it from there.
> 
> Actually, I tried this first but I had the impression that I start
> mixing stuff that somehow does not belong together.  That's why I
> started to restructure it.

I tried to add the missing information without restructuring, see
below.

> > Some specific comments and questions follow.
> >
> >> +When Emacs is running under a window system, reception of a SIGINT and
> >> +SIGQUIT will cause it to terminate.  It might therefore be useful to
> >> +configure the 'handle' command for those signals to use 'nopass', to
> >> +prevent Emacs from terminating on reception of such signals.
> >
> > I don't understand why is this useful.
> 
> Because it allows one to hit C-c in GDB, do some changes such as adding
> breakpoints and then continue.  With 'pass' it would terminate Emacs if
> it is run as a GUI application.  When run in a terminal, it does not
> terminate.  A nuance.

If we believe typing C-c when debugging GUI frames is a frequent
possibility, then we should change .gdbinit to support the above
automatically.  I don't think we should start explaining the
intricacies of signal handling in Emacs and in GDB in this file.

> >> +When using a window system, there is no reason for Emacs to handle C-g
> >> +as a SIGINT, as keyboard input is processed by the window system's
> >> +message pump.  Hence, no signal is sent as a response to a C-g.
> >
> > This explains how Emacs works, but I'm not sure it belongs in DEBUG.
> 
> True.  But I think such background information would have helped me a
> lot.

I understand, but if we start putting in this file everything that
someone found useful because they didn't know it beforehand, we will
end up with a huge and unmanageable file, I'm afraid.

> >> +When using X, type C-z at the window where Emacs is running under GDB,
> >> +and it will stop Emacs just as it would stop any ordinary program.
> >
> > The "window where Emacs is running under GDB" part is IMO confusing: I
> > couldn't figure out what window does this refer to.  There might not
> > be such a window at all, AFAIU.
> 
> To be honest, I don't understand this either.  But this was there
> before.  I just took it over and rephrased it slightly.  For example C-z
> in Gnome just minimizes the window (Emacs frame) AFAIK, but doesn't stop
> Emacs.  Do you know what C-z usually does in X window with a GUI
> application?  Does it send a signal to it?

I tried to clarify that, see below.

> > Next, what do you mean by "send a Ctrl-c or +Ctrl-Break to the
> > console"?  What console is alluded to here?
> 
> With new-console 1, when starting Emacs GUI, the console is visible as a
> separate window in MS-Windows.  And it is this console window that can
> be used to enter Ctrl-c or Ctrl-Break, even though we are running Emacs
> as a GUI application.

Are you sure?  I see something different here: when Emacs is started
after setting new-console, the window through which I interact with
GDB is the one where C-c causes GDB to get control back.  Maybe this
depends on the Windows version (it's XP down here, FWIW).

> > Finally, what does the "GDB treats them as a SIGINT, but Emacs won't
> > terminate as it ignores these events" part want to tell?  I couldn't
> > figure that out.
> That it behaves differently than on POSIX, where a SIGINT would
> terminate Emacs when running in "GUI mode".

That's actually inaccurate: on Windows, Emacs doesn't get a SIGINT in
this case, AFAIK.

> >>                                          or it will just ignore it
> >> +otherwise, as the event will be received by Emacs anyway when running
> >> +under the same terminal as GDB.
> >
> > This part is also confusing.  And I wonder why the signal-process
> > feature is not mentioned here.
> All processes sharing the same console will receive the C-c event.  In
> that case GDB doesn't have to escape to using DebugBreakProcess.  GDB
> just ignores C-c and Emacs will receive it anyway.  This was another
> thing that confused me.  That depenting on 'set new-console' setting,
> GDB signals either a SIGINT (due to C-c being received by Emacs) or a
> SIGTRAP (due to DebugBreakProcess) for the same initial C-c/SIGINT
> event.  A nuance.

I think we shouldn't even consider a use case when a text-mode Emacs
is debugged using the same terminal as the one used for communicating
with GDB.  It's not very practical to do so, since the GDB output is
mixed with Emacs's, and the result is a total mess.  Therefore,
allowing for that in the description just complicates the text for no
good reason.

> I hope I could clarify at least the intent of my change.  If you are
> still confused, I'll restart and try what you proposed: To find a way to
> only add missing information in the first place.  And to not rephrase
> existing content.

Please see if the alternative changes below catch everything that was
missing or inaccurate in the original text:

diff --git a/etc/DEBUG b/etc/DEBUG
index eef67da..7f3191d 100644
--- a/etc/DEBUG
+++ b/etc/DEBUG
@@ -190,24 +190,39 @@ kick in, provided that you run under GDB.
 
 ** Getting control to the debugger
 
+Setting a breakpoint in a strategic place, after loading Emacs into
+the debugger, but before running it, is the most efficient way of
+making sure control will be returned to the debugger when you need
+that.
+
 'Fsignal' is a very useful place to put a breakpoint in.  All Lisp
 errors go through there.  If you are only interested in errors that
 would fire the debugger, breaking at 'maybe_call_debugger' is useful.
 
-It is useful, when debugging, to have a guaranteed way to return to
-the debugger at any time.  When using X, this is easy: type C-z at the
-window where Emacs is running under GDB, and it will stop Emacs just
-as it would stop any ordinary program.  When Emacs is running in a
-terminal, things are not so easy.
+Another technique for get control to the debugger is to put a
+breakpoint in some rarely used function.  One such convenient function
+is Fredraw_display, which you can invoke at will interactively with
+"M-x redraw-display RET".
+
+It is also useful to have a guaranteed way to return to the debugger
+at any arbitrary time.  When using X, this is easy: type C-z at the
+window where you are interacting with GDB, and it will stop Emacs just
+as it would stop any ordinary program.  When Emacs is displaying on a
+text terminal, things are not so easy, so we describe the various
+alternatives below (however, those of them that use signals only work
+on Posix systems).
 
 The src/.gdbinit file in the Emacs distribution arranges for SIGINT
-(C-g in Emacs) to be passed to Emacs and not give control back to GDB.
-On modern POSIX systems, you can override that with this command:
+(C-g in Emacs on a text-mode frame) to be passed to Emacs and not give
+control back to GDB.  On modern POSIX systems, you can override that
+with this command:
 
    handle SIGINT stop nopass
 
 After this 'handle' command, SIGINT will return control to GDB.  If
 you want the C-g to cause a QUIT within Emacs as well, omit the 'nopass'.
+See the GDB manual for more details about signal handling and the
+'handle' command.
 
 A technique that can work when 'handle SIGINT' does not is to store
 the code for some character into the variable stop_character.  Thus,
@@ -216,26 +231,37 @@ the code for some character into the variable stop_character.  Thus,
 
 makes Control-] (decimal code 29) the stop character.
 Typing Control-] will cause immediate stop.  You cannot
-use the set command until the inferior process has been started.
-Put a breakpoint early in 'main', or suspend the Emacs,
-to get an opportunity to do the set command.
+use the set command until the inferior process has been started, so
+start Emacs with the 'start' command, to get an opportunity to do the
+above 'set' command.
 
-Another technique for get control to the debugger is to put a
-breakpoint in some rarely used function.  One such convenient function
-is Fredraw_display, which you can invoke at will interactively with
-"M-x redraw-display RET".
+On a Posix host, you can also send a signal using the 'kill' command
+from a shell prompt, like this:
 
-When Emacs is running in a terminal, it is sometimes useful to use a separate
-terminal for the debug session.  This can be done by starting Emacs as usual,
-then attaching to it from gdb with the 'attach' command which is explained in
-the node "Attach" of the GDB manual.
+   kill -TSTP Emacs-PID
 
-On MS-Windows, you can start Emacs in its own separate terminal by
+where Emacs-PID is the process ID of Emacs being debugged.  Other
+useful signals to send are SIGUSR1 and SIGUSR2; see "Error Debugging"
+in the ELisp manual for how to use those.
+
+When Emacs is displaying on a text terminal, it is sometimes useful to
+use a separate terminal for the debug session.  This can be done by
+starting Emacs as usual, then attaching to it from gdb with the
+'attach' command which is explained in the node "Attach" of the GDB
+manual.
+
+On MS-Windows, you can start Emacs from its own separate console by
 setting the new-console option before running Emacs under GDB:
 
   (gdb) set new-console 1
   (gdb) run
 
+If you do this, then typing C-c or C-BREAK into the console window
+through which you interact with GDB will stop Emacs and return control
+to the debugger, no matter if Emacs displays GUI or text-mode frames.
+This is the only reliable alternative on MS-Windows to get control to
+the debugger, besides setting breakpoints in advance.
+
 ** Examining Lisp object values.
 
 When you have a live process to debug, and it has not encountered a
@@ -848,7 +874,7 @@ directed to the xterm window you opened above.
 Similar arrangement is possible on a character terminal by using the
 'screen' package.
 
-On MS-Windows, you can start Emacs in its own separate terminal by
+On MS-Windows, you can start Emacs in its own separate console by
 setting the new-console option before running Emacs under GDB:
 
   (gdb) set new-console 1

Re: Revise etc/DEBUG documentation

[Noam Postavsky]

>  'Fsignal' is a very useful place to put a breakpoint in.  All Lisp
>  errors go through there.  If you are only interested in errors that
>  would fire the debugger, breaking at 'maybe_call_debugger' is useful.

I think it would be better to explicitly say "would fire the lisp
debugger" here, as "the debugger" mostly refers to GDB in this file.

Re: Revise etc/DEBUG documentation

[Eli Zaretskii]

> From: Noam Postavsky <npostavs@users.sourceforge.net>
> Date: Sat, 3 Sep 2016 11:05:20 -0400
> Cc: Alain Schneble <a.s@realize.ch>, Emacs developers <emacs-devel@gnu.org>
> 
> >  'Fsignal' is a very useful place to put a breakpoint in.  All Lisp
> >  errors go through there.  If you are only interested in errors that
> >  would fire the debugger, breaking at 'maybe_call_debugger' is useful.
> 
> I think it would be better to explicitly say "would fire the lisp
> debugger" here, as "the debugger" mostly refers to GDB in this file.

Good idea; done.

Re: Revise etc/DEBUG documentation

[Alain Schneble]

Eli Zaretskii <eliz@gnu.org> writes:

> I tried to find that boundary, see below.

Ok, thanks.

> In general, etc/DEBUG is supposed to be a cookbook-like collection of
> tips, not a full-fledged manual.

I see.

> I tried to add the missing information without restructuring, see
> below.

That is very obliging.

>> Because it allows one to hit C-c in GDB, do some changes such as adding
>> breakpoints and then continue.  With 'pass' it would terminate Emacs if
>> it is run as a GUI application.  When run in a terminal, it does not
>> terminate.  A nuance.
>
> If we believe typing C-c when debugging GUI frames is a frequent
> possibility, then we should change .gdbinit to support the above
> automatically.  I don't think we should start explaining the
> intricacies of signal handling in Emacs and in GDB in this file.

Ok.  Good idea.  But not sure if we can distinguish between executing
Emacs as GUI or terminal application in .gdbinit.  Because for the
latter, we certainly still want it to 'pass' (as it is currently
arranged for in .gdbinit).

> I understand, but if we start putting in this file everything that
> someone found useful because they didn't know it beforehand, we will
> end up with a huge and unmanageable file, I'm afraid.

I was certainly biased by my personal findings that helped me to
understand the mechanisms, I agree.

>> To be honest, I don't understand this either.  But this was there
>> before.  I just took it over and rephrased it slightly.  For example C-z
>> in Gnome just minimizes the window (Emacs frame) AFAIK, but doesn't stop
>> Emacs.  Do you know what C-z usually does in X window with a GUI
>> application?  Does it send a signal to it?
>
> I tried to clarify that, see below.

Thanks.

>> With new-console 1, when starting Emacs GUI, the console is visible as a
>> separate window in MS-Windows.  And it is this console window that can
>> be used to enter Ctrl-c or Ctrl-Break, even though we are running Emacs
>> as a GUI application.
>
> Are you sure?  I see something different here: when Emacs is started
> after setting new-console, the window through which I interact with
> GDB is the one where C-c causes GDB to get control back.  Maybe this
> depends on the Windows version (it's XP down here, FWIW).

I think I was again not clear enough, sorry. FWIW, what I meant is:

start a new command prompt
gdb
file emacs
set new-console 1
run

=> there are three windows: 1) GDB console, 2) Emacs console
(empty/"black" window) and 3) Emacs GUI window.

What I wanted to say is that one /can/ use 2) to enter C-c or C-break as
well. This results in GDB displaying 'Thread [n] received signal SIGINT,
Interrupt.'.

Of course you can use 1) as well.  But this will show a SIGTRAP instead
of a SIGINT message in GDB ('Thread [m] received signal SIGTRAP,
Trace/breakpoint trap').  Because 1) and 2) do not share the same
console, GDB can't send a GenerateConoleCtrlEvent and it falls back to
DebugBreakProcess.  That's the reason for the differernt behavior.

That was what confused me while studying the behavior.  BTW, I don't
think that this is different on XP (I tested this on MS Windows 10
here).  Is it?

>> That it behaves differently than on POSIX, where a SIGINT would
>> terminate Emacs when running in "GUI mode".
>
> That's actually inaccurate: on Windows, Emacs doesn't get a SIGINT in
> this case, AFAIK.

Well, see my example above.  At least GDB shows it as a SIGINT.

> I think we shouldn't even consider a use case when a text-mode Emacs
> is debugged using the same terminal as the one used for communicating
> with GDB.  It's not very practical to do so, since the GDB output is
> mixed with Emacs's, and the result is a total mess.  Therefore,
> allowing for that in the description just complicates the text for no
> good reason.

I was talking about Emacs *with GUI* started after 'set new-console 1'
here.  But after reading the paragraph again, I realized that I forgot
to mention it -- my apologies.

>> I hope I could clarify at least the intent of my change.  If you are
>> still confused, I'll restart and try what you proposed: To find a way to
>> only add missing information in the first place.  And to not rephrase
>> existing content.
>
> Please see if the alternative changes below catch everything that was
> missing or inaccurate in the original text:

Thank you very much.

> diff --git a/etc/DEBUG b/etc/DEBUG
> index eef67da..7f3191d 100644
> --- a/etc/DEBUG
> +++ b/etc/DEBUG
> @@ -190,24 +190,39 @@ kick in, provided that you run under GDB.
>  
>  ** Getting control to the debugger
>  
> +Setting a breakpoint in a strategic place, after loading Emacs into
> +the debugger, but before running it, is the most efficient way of
> +making sure control will be returned to the debugger when you need
> +that.
> +

Perfect.

>  'Fsignal' is a very useful place to put a breakpoint in.  All Lisp
>  errors go through there.  If you are only interested in errors that
>  would fire the debugger, breaking at 'maybe_call_debugger' is useful.
>  
> -It is useful, when debugging, to have a guaranteed way to return to
> -the debugger at any time.  When using X, this is easy: type C-z at the
> -window where Emacs is running under GDB, and it will stop Emacs just
> -as it would stop any ordinary program.  When Emacs is running in a
> -terminal, things are not so easy.
> +Another technique for get control to the debugger is to put a
> +breakpoint in some rarely used function.  One such convenient function
> +is Fredraw_display, which you can invoke at will interactively with
> +"M-x redraw-display RET".
> +
> +It is also useful to have a guaranteed way to return to the debugger
> +at any arbitrary time.  When using X, this is easy: type C-z at the
> +window where you are interacting with GDB, and it will stop Emacs just
> +as it would stop any ordinary program.  When Emacs is displaying on a
> +text terminal, things are not so easy, so we describe the various
> +alternatives below (however, those of them that use signals only work
> +on Posix systems).

Now it's clear to me as well.  Thanks.

>  The src/.gdbinit file in the Emacs distribution arranges for SIGINT
> -(C-g in Emacs) to be passed to Emacs and not give control back to GDB.
> -On modern POSIX systems, you can override that with this command:
> +(C-g in Emacs on a text-mode frame) to be passed to Emacs and not give
> +control back to GDB.  On modern POSIX systems, you can override that
> +with this command:
>  
>     handle SIGINT stop nopass
>  
>  After this 'handle' command, SIGINT will return control to GDB.  If
>  you want the C-g to cause a QUIT within Emacs as well, omit the 'nopass'.
> +See the GDB manual for more details about signal handling and the
> +'handle' command.

Fair enough.

>  A technique that can work when 'handle SIGINT' does not is to store
>  the code for some character into the variable stop_character.  Thus,
> @@ -216,26 +231,37 @@ the code for some character into the variable stop_character.  Thus,
>  
>  makes Control-] (decimal code 29) the stop character.
>  Typing Control-] will cause immediate stop.  You cannot
> -use the set command until the inferior process has been started.
> -Put a breakpoint early in 'main', or suspend the Emacs,
> -to get an opportunity to do the set command.
> +use the set command until the inferior process has been started, so
> +start Emacs with the 'start' command, to get an opportunity to do the
> +above 'set' command.
>  
> -Another technique for get control to the debugger is to put a
> -breakpoint in some rarely used function.  One such convenient function
> -is Fredraw_display, which you can invoke at will interactively with
> -"M-x redraw-display RET".
> +On a Posix host, you can also send a signal using the 'kill' command
> +from a shell prompt, like this:
>  
> -When Emacs is running in a terminal, it is sometimes useful to use a separate
> -terminal for the debug session.  This can be done by starting Emacs as usual,
> -then attaching to it from gdb with the 'attach' command which is explained in
> -the node "Attach" of the GDB manual.
> +   kill -TSTP Emacs-PID
>  
> -On MS-Windows, you can start Emacs in its own separate terminal by
> +where Emacs-PID is the process ID of Emacs being debugged.  Other
> +useful signals to send are SIGUSR1 and SIGUSR2; see "Error Debugging"
> +in the ELisp manual for how to use those.
> +
> +When Emacs is displaying on a text terminal, it is sometimes useful to
                                                ^^^^^^^^^^^^^^^^^^^^^^
Isn't this always useful or even required?  Or is there a standard use
case that requires not doing so?

> +use a separate terminal for the debug session.  This can be done by
> +starting Emacs as usual, then attaching to it from gdb with the
> +'attach' command which is explained in the node "Attach" of the GDB
> +manual.
> +
> +On MS-Windows, you can start Emacs from its own separate console by

Using here the term console instead of terminal is wise.

>  setting the new-console option before running Emacs under GDB:
>  
>    (gdb) set new-console 1
>    (gdb) run
>  
> +If you do this, then typing C-c or C-BREAK into the console window
> +through which you interact with GDB will stop Emacs and return control
> +to the debugger, no matter if Emacs displays GUI or text-mode frames.
> +This is the only reliable alternative on MS-Windows to get control to
> +the debugger, besides setting breakpoints in advance.
> +
>  ** Examining Lisp object values.
>  
>  When you have a live process to debug, and it has not encountered a
> @@ -848,7 +874,7 @@ directed to the xterm window you opened above.
>  Similar arrangement is possible on a character terminal by using the
>  'screen' package.
>  
> -On MS-Windows, you can start Emacs in its own separate terminal by
> +On MS-Windows, you can start Emacs in its own separate console by
>  setting the new-console option before running Emacs under GDB:
>  
>    (gdb) set new-console 1

I agree with your changes.  These are the important points.  Thanks for
your help.

Re: Revise etc/DEBUG documentation

[Eli Zaretskii]

> From: Alain Schneble <a.s@realize.ch>
> CC: <emacs-devel@gnu.org>
> Date: Sat, 3 Sep 2016 23:51:30 +0200
> 
> not sure if we can distinguish between executing
> Emacs as GUI or terminal application in .gdbinit.  Because for the
> latter, we certainly still want it to 'pass' (as it is currently
> arranged for in .gdbinit).

It is actually more complicated than that, because the same Emacs
session could have some GUI frames and some text-mode frames (though
not on MS-Windows).  That's why saying "Emacs executes as GUI" is
problematic at best.

> >> With new-console 1, when starting Emacs GUI, the console is visible as a
> >> separate window in MS-Windows.  And it is this console window that can
> >> be used to enter Ctrl-c or Ctrl-Break, even though we are running Emacs
> >> as a GUI application.
> >
> > Are you sure?  I see something different here: when Emacs is started
> > after setting new-console, the window through which I interact with
> > GDB is the one where C-c causes GDB to get control back.  Maybe this
> > depends on the Windows version (it's XP down here, FWIW).
> 
> I think I was again not clear enough, sorry. FWIW, what I meant is:
> 
> start a new command prompt
> gdb
> file emacs
> set new-console 1
> run
> 
> => there are three windows: 1) GDB console, 2) Emacs console
> (empty/"black" window) and 3) Emacs GUI window.
> 
> What I wanted to say is that one /can/ use 2) to enter C-c or C-break as
> well. This results in GDB displaying 'Thread [n] received signal SIGINT,
> Interrupt.'.

I understood what you were saying.  But your description doesn't match
what I see here.  (And no, it's not OS version dependent, as I see the
same on Windows 7 as on XP.)  My crystal ball says that you see that
in a session which either didn't read src/.gdbinit, or you manually
issued a 'handle' command that changes how SIGINT is handled by GDB,
because under the default setting in .gdbinit, SIGINT has the
"noprint" attribute, which implies "nostop".

Or maybe you are using some build of GDB that is very different from
what I'm using (like the Cygwin build?).  Or maybe some other factor
is at work here.

> Of course you can use 1) as well.  But this will show a SIGTRAP instead
> of a SIGINT message in GDB ('Thread [m] received signal SIGTRAP,
> Trace/breakpoint trap').

From the user POV, the difference is unimportant, the important part
is to get control back to GDB.

> >> That it behaves differently than on POSIX, where a SIGINT would
> >> terminate Emacs when running in "GUI mode".
> >
> > That's actually inaccurate: on Windows, Emacs doesn't get a SIGINT in
> > this case, AFAIK.
> 
> Well, see my example above.  At least GDB shows it as a SIGINT.

Not by default, not when using .gdbinit from the Emacs sources.

> > +When Emacs is displaying on a text terminal, it is sometimes useful to
>                                                 ^^^^^^^^^^^^^^^^^^^^^^
> Isn't this always useful or even required?  Or is there a standard use
> case that requires not doing so?

Yes, deleting the "sometimes" part would be beneficial, thanks.

> I agree with your changes.  These are the important points.  Thanks for
> your help.

Thanks, I will install this in a short while.

Re: Revise etc/DEBUG documentation

[Alain Schneble]

Eli Zaretskii <eliz@gnu.org> writes:

> It is actually more complicated than that, because the same Emacs
> session could have some GUI frames and some text-mode frames (though
> not on MS-Windows).  That's why saying "Emacs executes as GUI" is
> problematic at best.

I didn't even know that this is possible.  Thanks for pointing it out.

> I understood what you were saying.  But your description doesn't match
> what I see here.  (And no, it's not OS version dependent, as I see the
> same on Windows 7 as on XP.)  My crystal ball says that you see that
> in a session which either didn't read src/.gdbinit, or you manually
> issued a 'handle' command that changes how SIGINT is handled by GDB,
> because under the default setting in .gdbinit, SIGINT has the
> "noprint" attribute, which implies "nostop".

Your crystal ball told you the truth.  In my session, it did not
properly load src/.gdbinit as I started gdb without specifying an
executable file as command line args.  In this case, the line 'set
$dummy = main + 8' in .gdbinit issues an error and script execution
stops.  Hence, all the 'handle' commands that follow were not executed.
I must have overlooked that.  I'm sorry.

>> Of course you can use 1) as well.  But this will show a SIGTRAP instead
>> of a SIGINT message in GDB ('Thread [m] received signal SIGTRAP,
>> Trace/breakpoint trap').
>
> From the user POV, the difference is unimportant, the important part
> is to get control back to GDB.

Indeed.

>> > +When Emacs is displaying on a text terminal, it is sometimes useful to
>>                                                 ^^^^^^^^^^^^^^^^^^^^^^
>> Isn't this always useful or even required?  Or is there a standard use
>> case that requires not doing so?
>
> Yes, deleting the "sometimes" part would be beneficial, thanks.

Thanks.

>> I agree with your changes.  These are the important points.  Thanks for
>> your help.
>
> Thanks, I will install this in a short while.

Thank you.

Re: Revise etc/DEBUG documentation

[Eli Zaretskii]

> From: Alain Schneble <a.s@realize.ch>
> CC: <emacs-devel@gnu.org>
> Date: Sun, 4 Sep 2016 18:24:30 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > It is actually more complicated than that, because the same Emacs
> > session could have some GUI frames and some text-mode frames (though
> > not on MS-Windows).  That's why saying "Emacs executes as GUI" is
> > problematic at best.
> 
> I didn't even know that this is possible.  Thanks for pointing it out.

See keyboard.c:handle_interrupt_signal for how that complication is
handled.

Btw, I found that the MS-Windows build wasn't catching SIGINT in GUI
sessions like the Posix platforms do, and I will fix that in a few
moments.

> >> I agree with your changes.  These are the important points.  Thanks for
> >> your help.
> >
> > Thanks, I will install this in a short while.
> 
> Thank you.

Done.

Re: Revise etc/DEBUG documentation

[Eli Zaretskii]

> Date: Mon, 05 Sep 2016 19:36:46 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: emacs-devel@gnu.org
> 
> Btw, I found that the MS-Windows build wasn't catching SIGINT in GUI
> sessions like the Posix platforms do, and I will fix that in a few
> moments.

Now fixed on the master branch.

Re: Revise etc/DEBUG documentation

[Alain Schneble]

Eli Zaretskii <eliz@gnu.org> writes:

>> > It is actually more complicated than that, because the same Emacs
>> > session could have some GUI frames and some text-mode frames (though
>> > not on MS-Windows).  That's why saying "Emacs executes as GUI" is
>> > problematic at best.
>> 
>> I didn't even know that this is possible.  Thanks for pointing it out.
>
> See keyboard.c:handle_interrupt_signal for how that complication is
> handled.

Thanks.  Now I think I finally understand what the comment about
multiple display types and SIGINT in init_keyboard.c:10886 (cfaf18a)
really means :)

> Btw, I found that the MS-Windows build wasn't catching SIGINT in GUI
> sessions like the Posix platforms do, and I will fix that in a few
> moments.

That was exactly one of the things that confused me and what I tried to
document in my initial patch by saying

"On MS-Windows, [...].  GDB treats them as a SIGINT, but Emacs
won't terminate as it ignores these events."
                      ^^^^^^^^^^^^^^^^^^^^
With this fix, this confusion is gone.  Thanks.

Just one small thing: After sending a SIGINT, it might take some time
until Emacs actually terminates as it might be blocked in pselect
emulation (sys_select) in the call to MsgWaitForMultipleObjects.  Just
wonder if there is an easy way to send a message or such to get out of
the blocking call without having to wait for a timeout or another event
to happen.  I guess that does not happen on POSIX as the corresponding
syscall will be interrupted anyway, right?

Re: Revise etc/DEBUG documentation

[Alain Schneble]

Alain Schneble <a.s@realize.ch> writes:

> Just one small thing: After sending a SIGINT, it might take some time
> until Emacs actually terminates as it might be blocked in pselect
> emulation (sys_select) in the call to MsgWaitForMultipleObjects.  Just
> wonder if there is an easy way to send a message or such to get out of
> the blocking call without having to wait for a timeout or another event
> to happen.  I guess that does not happen on POSIX as the corresponding
> syscall will be interrupted anyway, right?

AFAICS, this indeed doesn't happen on a POSIX system.

Re: Revise etc/DEBUG documentation

[Eli Zaretskii]

> From: Alain Schneble <a.s@realize.ch>
> CC: <emacs-devel@gnu.org>
> Date: Mon, 5 Sep 2016 21:19:58 +0200
> 
> Just one small thing: After sending a SIGINT, it might take some time
> until Emacs actually terminates as it might be blocked in pselect
> emulation (sys_select) in the call to MsgWaitForMultipleObjects.  Just
> wonder if there is an easy way to send a message or such to get out of
> the blocking call without having to wait for a timeout or another event
> to happen.

Are you sure the delay is because of Emacs being parked in pselect?
In my testing, Emacs shuts down after C-c as soon as it gets focus.

> I guess that does not happen on POSIX as the corresponding syscall
> will be interrupted anyway, right?

If that's the reason, probably.  There are no signals on Windows, in
the Posix sense.

Re: Revise etc/DEBUG documentation

[Alain Schneble]

Eli Zaretskii <eliz@gnu.org> writes:

> Are you sure the delay is because of Emacs being parked in pselect?
> In my testing, Emacs shuts down after C-c as soon as it gets focus.

Yes, I'm sure.  At least this is what I'm observing here (with DebPrint
calls).  And yes, as soon as the frame gets focus or receives any other
MS Windows message such as WM_MOUSEMOVE (or any subprocess output), it
will terminate.  But if not, it blocks until the timeout expires.

This potential delay is a minor detail.  But couldn't we overcome it by
pulsing the interrupt_handle event, e.g. by a call to signal_quit in
keyboard.c (handle_interrupt_signal), just after having set the
Vquit_flag?  Of course, that would be for MS Windows only.

Re: Revise etc/DEBUG documentation

[Eli Zaretskii]

> From: Alain Schneble <a.s@realize.ch>
> CC: <emacs-devel@gnu.org>
> Date: Tue, 6 Sep 2016 12:06:24 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Are you sure the delay is because of Emacs being parked in pselect?
> > In my testing, Emacs shuts down after C-c as soon as it gets focus.
> 
> Yes, I'm sure.  At least this is what I'm observing here (with DebPrint
> calls).  And yes, as soon as the frame gets focus or receives any other
> MS Windows message such as WM_MOUSEMOVE (or any subprocess output), it
> will terminate.  But if not, it blocks until the timeout expires.

But in that case, this is expected behavior: the SIGINT handler just
sets a flag and returns; the flag is then processed whenever the Emacs
event loop cranks one more cycle.  This is not specific to MS-Windows.
In an idle "emacs -Q", you might indeed see a difference between
Windows and Posix systems, because on the latter pselect will be
interrupted by SIGINT.  But that is not a very interesting use case
for shutting down Emacs with SIGINT.  A real-life Emacs session has
several timers running, which typically make pselect waits shorter,
and if Emacs is in the middle of some prolonged computation, you will
see a delay on Posix platforms as well.

IOW, Emacs behaves here as expected, on Windows and elsewhere.

> This potential delay is a minor detail.  But couldn't we overcome it by
> pulsing the interrupt_handle event, e.g. by a call to signal_quit in
> keyboard.c (handle_interrupt_signal), just after having set the
> Vquit_flag?  Of course, that would be for MS Windows only.

I see no reason, see above.  In any case, I'd advise against doing
anything non-trivial in the SIGINT handler, on Windows in particular,
because Windows runs such handlers in a separate thread, so it's
unsafe to do there anything non-trivial -- we could easily crash,
because we are on the wrong stack.

Re: Revise etc/DEBUG documentation

[Alain Schneble]

Eli Zaretskii <eliz@gnu.org> writes:

> But in that case, this is expected behavior: the SIGINT handler just
> sets a flag and returns; the flag is then processed whenever the Emacs
> event loop cranks one more cycle.  This is not specific to MS-Windows.
> In an idle "emacs -Q", you might indeed see a difference between
> Windows and Posix systems, because on the latter pselect will be
> interrupted by SIGINT.

Exactly.  This was the unexpected behavior I was referring to.

>                         But that is not a very interesting use case
> for shutting down Emacs with SIGINT.  A real-life Emacs session has
> several timers running, which typically make pselect waits shorter,
> and if Emacs is in the middle of some prolonged computation, you will
> see a delay on Posix platforms as well.

Indeed.

> IOW, Emacs behaves here as expected, on Windows and elsewhere.

I looked at it as a white box, and this was not what /I/ expected.  From
a users point of view and when looking at real cases, it doesn't really
matter, I agree.

>> This potential delay is a minor detail.  But couldn't we overcome it by
>> pulsing the interrupt_handle event, e.g. by a call to signal_quit in
>> keyboard.c (handle_interrupt_signal), just after having set the
>> Vquit_flag?  Of course, that would be for MS Windows only.
>
> I see no reason, see above.  In any case, I'd advise against doing
> anything non-trivial in the SIGINT handler, on Windows in particular,
> because Windows runs such handlers in a separate thread, so it's
> unsafe to do there anything non-trivial -- we could easily crash,
> because we are on the wrong stack.

Ok, sure.  (Even though I don't think that PulseEvent would do any hurt
here...)

Thanks for your explanations.

Re: Revise etc/DEBUG documentation

[Alain Schneble]

Alain Schneble <a.s@realize.ch> writes:

> Ok, sure.  (Even though I don't think that PulseEvent would do any hurt
> here...)
                                                                     ^^^^
                                                                     harm

... of course ;)

Re: Revise etc/DEBUG documentation

[Davis Herring]

> +It is also useful to have a guaranteed way to return to the debugger
> +at any arbitrary time.  When using X, this is easy: type C-z at the
> +window where you are interacting with GDB, and it will stop Emacs just
> +as it would stop any ordinary program.  When Emacs is displaying on a

I know this is largely old text, but while we're editing it: if GDB was 
attached to a running process ("gdb -p ..."), C-z sent to GDB's terminal 
will just suspend GDB.  With SIGINT set to nostop, you can't stop the 
program from GDB: you have to use its controlling terminal (C-z or C-\, 
since C-c is nostop even thence) if it has one, or else kill(1).

Davis

-- 
This product is sold by volume, not by mass.  If it appears too dense or 
too sparse, it is because mass-energy conversion has occurred during 
shipping.

Re: Revise etc/DEBUG documentation

[Eli Zaretskii]

> Cc: Alain Schneble <a.s@realize.ch>, emacs-devel@gnu.org
> From: Davis Herring <herring@lanl.gov>
> Date: Tue, 6 Sep 2016 15:52:02 -0600
> 
> I know this is largely old text, but while we're editing it: if GDB was 
> attached to a running process ("gdb -p ..."), C-z sent to GDB's terminal 
> will just suspend GDB.  With SIGINT set to nostop, you can't stop the 
> program from GDB: you have to use its controlling terminal (C-z or C-\, 
> since C-c is nostop even thence) if it has one, or else kill(1).

Thanks, fixed.