Re: [PATCH] Clarify "maint set target-non-stop" in GDB manual (Re: [PATCH v3 00/11] Windows non-stop mode)

[Eli Zaretskii <eliz@gnu.org>]

> Date: Thu, 30 Apr 2026 15:15:42 +0100
> From: Pedro Alves <pedro@palves.net>
> Cc: ssbssa@yahoo.de, gdb-patches@sourceware.org
> 
> > OK, I can take a look at this.
> 
> How about this below?
> 
> Note I added a note saying that this isn't useful to users, but note that the maint commands appendix already starts with:
> 
>   "In addition to commands intended for GDB users, GDB includes a number of commands intended for GDB developers, that are not documented elsewhere in this manual. 

Thanks.

> +The following @code{set non-stop off} combinations are valid:

Shouldn't it also say something about "set non-stop on"?

> +@table @code
> +@item @code{set non-stop off}, target operating in all-stop mode
> +When a @value{GDBN} target is operating in all-stop mode, then when
> +a thread hits a breakpoint, finishes a step, etc., the target stops
> +all threads, and reports the event to the infrun module in the core of
> +@value{GDBN}.  If infrun decides the stop is not to be seen by the
> +user, infrun re-resumes all threads again.  In other words, all
> +threads stop and are re-resumed for every debug event, even for debug
> +events that are internal and do not cause a user-visible stop.
> +
> +@item @code{set non-stop off}, target operating in non-stop mode
> +When a @value{GDBN} target is operating in non-stop mode in
> +combination with @code{set non-stop} set to @code{off}, it is said
> +that @value{GDBN} is operating in ``all-stop on top of non-stop''.  In
> +this scenario, when a thread hits a breakpoint, finishes a step, etc.,
> +the target does not immediately stop all other threads.  If, while
> +processing the event, infrun decides the stop should be reported to
> +the user, it then explicitly stops all threads, just before presenting
> +the stop to the user; otherwise, infrun re-resumes the stopped thread.
> +@end table

The second @item says "...in combination with @code{set non-stop} set
to @code{off}", which is a Good Thing, but the first @item doesn't say
the same about the "on" setting.  I suggest to make the style more
consistent.

Also, what about the description of "set non-stop", the user-level
command?  It currently doesn't even say what is the default.  In
addition, the fact that its description says "Enable selection of
non-stop mode" is confusing, because it makes it sound like there's
some other command to actually "select" the non-stop mode.  The text
which attempts to explain the "enable" part, viz.:

     Note these commands only reflect whether non-stop mode is enabled,
  not whether the currently-executing program is being run in non-stop
  mode.  In particular, the 'set non-stop' preference is only consulted
  when GDB starts or connects to the target program, and it is generally
  not possible to switch modes once debugging has started.  Furthermore,
  since not all targets support non-stop mode, even when you have enabled
  non-stop mode, GDB may still fall back to all-stop operation by default.

doesn't really justify the "enable" part.  It won't surprise anyone
that "set non-stop on" will only work if the target doesn't support
it, and the fact that this command only affects the next inferior to
be started is just a factoid to be mentioned, but it again doesn't
justify the "enable" confusion, IMO.