Ping: [RFA] [Doc] Non-stop mode user documentation

[Sandra Loosemore <sandra at codesourcery dot com>]

Ping?

http://sourceware.org/ml/gdb-patches/2008-07/msg00520.html

I've attached a new version of the patch with a fix for a typo I spotted after 
submitting the original version.

-Sandra

2008-08-10  Sandra Loosemore  <sandra@codesourcery.com>
	    Pedro Alves  <pedro@codesourcery.com>

	gdb/doc
	* gdb.texinfo (Threads): Move paragraph about automatic thread
	selection to All-Stop Mode subsection.
	(Thread Stops): Reorganize existing material into subsections.
	Add introductory blurb and menu.
	(Non-Stop Mode): New subsection.
	(Background Execution): New subsection.
	(Maintenance Commands): Add cross-references from async mode
	commands to the new Background Execution section.

Index: gdb/doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.509
diff -c -3 -p -r1.509 gdb.texinfo
*** gdb/doc/gdb.texinfo	18 Jul 2008 20:55:33 -0000	1.509
--- gdb/doc/gdb.texinfo	27 Jul 2008 22:43:41 -0000
*************** Show whether messages will be printed wh
*** 2591,2605 ****
  have started and exited.
  @end table
  
- @cindex automatic thread selection
- @cindex switching threads automatically
- @cindex threads, automatic switching
- Whenever @value{GDBN} stops your program, due to a breakpoint or a
- signal, it automatically selects the thread where that breakpoint or
- signal happened.  @value{GDBN} alerts you to the context switch with a
- message of the form @samp{[Switching to @var{systag}]} to identify the
- thread.
- 
  @xref{Thread Stops,,Stopping and Starting Multi-thread Programs}, for
  more information about how @value{GDBN} behaves when you stop and start
  programs with multiple threads.
--- 2591,2596 ----
*************** Program a Signal}.
*** 4459,4464 ****
--- 4450,4718 ----
  @node Thread Stops
  @section Stopping and Starting Multi-thread Programs
  
+ @cindex stopped threads
+ @cindex threads, stopped
+ 
+ @cindex continuing threads
+ @cindex threads, continuing
+ 
+ @value{GDBN} supports debugging programs with multiple threads
+ (@pxref{Threads,, Debugging Programs with Multiple Threads}).  There
+ are two modes of controlling execution of your program within the
+ debugger.  In the default mode, referred to as @dfn{all-stop mode},
+ when any thread in your program stops (for example, at a breakpoint 
+ or while being stepped), all other threads in the program are also stopped by 
+ @value{GDBN}.  On some targets, @value{GDBN} also supports 
+ @dfn{non-stop mode}, in which other threads can continue to run freely while
+ you examine the stopped thread in the debugger.
+ 
+ @menu
+ * All-Stop Mode::		All threads stop when GDB takes control
+ * Non-Stop Mode::		Other threads continue to execute
+ * Background Execution::	Running your program asynchronously
+ * Thread-Specific Breakpoints::	Controlling breakpoints
+ * Interrupted System Calls::	GDB may interfere with system calls
+ @end menu
+ 
+ @node All-Stop Mode
+ @subsection All-Stop Mode
+ 
+ @cindex all-stop mode
+ 
+ In all-stop mode, whenever your program stops under @value{GDBN} for any reason,
+ @emph{all} threads of execution stop, not just the current thread.  This
+ allows you to examine the overall state of the program, including
+ switching between threads, without worrying that things may change
+ underfoot.
+ 
+ Conversely, whenever you restart the program, @emph{all} threads start
+ executing.  @emph{This is true even when single-stepping} with commands
+ like @code{step} or @code{next}.
+ 
+ In particular, @value{GDBN} cannot single-step all threads in lockstep.
+ Since thread scheduling is up to your debugging target's operating
+ system (not controlled by @value{GDBN}), other threads may
+ execute more than one statement while the current thread completes a
+ single step.  Moreover, in general other threads stop in the middle of a
+ statement, rather than at a clean statement boundary, when the program
+ stops.
+ 
+ You might even find your program stopped in another thread after
+ continuing or even single-stepping.  This happens whenever some other
+ thread runs into a breakpoint, a signal, or an exception before the
+ first thread completes whatever you requested.
+ 
+ @cindex automatic thread selection
+ @cindex switching threads automatically
+ @cindex threads, automatic switching
+ Whenever @value{GDBN} stops your program, due to a breakpoint or a
+ signal, it automatically selects the thread where that breakpoint or
+ signal happened.  @value{GDBN} alerts you to the context switch with a
+ message of the form @samp{[Switching to @var{systag}]} to identify the
+ thread.
+ 
+ On some OSes, you can modify @value{GDBN}'s default behavior by
+ locking the OS scheduler to allow only a single thread to run.
+ 
+ @table @code
+ @item set scheduler-locking @var{mode}
+ @cindex scheduler locking mode
+ @cindex lock scheduler
+ Set the scheduler locking mode.  If it is @code{off}, then there is no
+ locking and any thread may run at any time.  If @code{on}, then only the
+ current thread may run when the inferior is resumed.  The @code{step}
+ mode optimizes for single-stepping.  It stops other threads from
+ ``seizing the prompt'' by preempting the current thread while you are
+ stepping.  Other threads will only rarely (or never) get a chance to run
+ when you step.  They are more likely to run when you @samp{next} over a
+ function call, and they are completely free to run when you use commands
+ like @samp{continue}, @samp{until}, or @samp{finish}.  However, unless another
+ thread hits a breakpoint during its timeslice, they will never steal the
+ @value{GDBN} prompt away from the thread that you are debugging.
+ 
+ @item show scheduler-locking
+ Display the current scheduler locking mode.
+ @end table
+ 
+ @node Non-Stop Mode
+ @subsection Non-Stop Mode
+ 
+ @cindex non-stop mode
+ 
+ @c This section is really only a place-holder, and needs to be expanded
+ @c with more details.  
+ 
+ For some multi-threaded targets, @value{GDBN} supports an optional
+ mode of operation in which you can examine stopped program threads in
+ the debugger while other threads continue to execute freely.  This
+ minimizes intrusion when debugging live systems, such as programs 
+ where some threads have real-time constraints or must continue to 
+ respond to external events.  This is referred to as @dfn{non-stop} mode.
+ 
+ In non-stop mode, when a thread stops to report a debugging event,
+ @emph{only} that thread is stopped; @value{GDBN} does not stop other
+ threads as well, in contrast to the all-stop mode behavior.  Additionally,
+ execution commands such as @code{continue} and @code{step} apply by default
+ only to the current thread in non-stop mode, rather than all threads as
+ in all-stop mode.  This allows you to control threads explicitly in
+ ways that are not possible in all-stop mode --- for example, stepping 
+ one thread while allowing others to run freely, stepping
+ one thread while holding all others stopped, or stepping several threads 
+ independently and simultaneously.
+ 
+ To enter non-stop mode, use this sequence of commands before you run
+ or attach to your program:
+ 
+ @c FIXME: can we fix this recipe to avoid the linux-async/remote-async details?
+ 
+ @smallexample
+ # Enable the async interface.  
+ # For target remote, use remote-async instead of linux-async.
+ maint set linux-async 1
+ 
+ # With non-stop, breakpoints have to be always inserted.
+ set breakpoint always-inserted 1
+ 
+ # If using the CLI, pagination breaks non-stop.
+ set pagination off
+ 
+ # Finally, turn it on!
+ set non-stop on
+ @end smallexample
+ 
+ You can use these commands to manipulate the non-stop mode setting:
+ 
+ @table @code
+ @kindex set non-stop
+ @item set non-stop on
+ Enable selection of non-stop mode.
+ @item set non-stop off
+ Disable selection of non-stop mode.
+ @kindex show non-stop
+ @item show non-stop
+ Show the current non-stop enablement setting.
+ @end table
+ 
+ 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 @code{set non-stop} preference is only consulted when
+ @value{GDBN} 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, @value{GDBN} may still fall back to all-stop operation by
+ default.
+ 
+ In non-stop mode, all execution commands apply only to the current thread
+ by default.  That is, @code{continue} only continues one thread.  
+ To continue all threads, issue @code{continue -a} or @code{c -a}.
+ 
+ You can use @value{GDBN}'s background execution commands 
+ (@pxref{Background Execution}) to run some threads in the background
+ while you continue to examine or step others from @value{GDBN}.  
+ The MI execution commands (@pxref{GDB/MI Program Execution}) are
+ always executed asynchronously in non-stop mode.
+ 
+ Suspending execution is done with the @code{interrupt} command when
+ running in the background, or @kbd{Ctrl-c} during foreground execution.  
+ In all-stop mode, this stops the whole process; 
+ but in non-stop mode the interrupt applies only to the current thread.  
+ To stop the whole program, use @code{interrupt -a}.
+ 
+ Other execution commands do not currently support the @code{-a} option.
+ 
+ In non-stop mode, when a thread stops, @value{GDBN} doesn't automatically make
+ that thread current, as it does in all-stop mode.  This is because the
+ thread stop notifications are asynchronous with respect to @value{GDBN}'s 
+ command interpreter, and it would be confusing if @value{GDBN} unexpectedly
+ changed to a different thread just as you entered a command to operate on the
+ previously current thread.
+ 
+ @node Background Execution
+ @subsection Background Execution
+ 
+ @cindex foreground execution
+ @cindex execution, foreground
+ @cindex background execution
+ @cindex execution, background
+ @cindex asynchronous execution
+ @cindex execution, asynchronous
+ 
+ @value{GDBN}'s execution commands have two variants:  the normal
+ foreground (synchronous) behavior, and a background
+ (asynchronous) behavior.  In foreground execution, @value{GDBN} waits for 
+ the program to report that some thread has stopped before prompting for
+ another command.  In background execution, @value{GDBN} immediately gives
+ a command prompt so that you issue other commands while your program runs.
+ 
+ To specify background execution, add a @code{&} to the command.  For example,
+ the background form of the @code{continue} command is @code{continue&}, or
+ just @code{c&}.  The execution commands that accept background execution
+ are:
+ 
+ @table @code
+ @kindex run&
+ @item run
+ @xref{Starting, , Starting your Program}.
+ 
+ @item attach
+ @kindex attach&
+ @xref{Attach, , Debugging an Already-running Process}.
+ 
+ @item step
+ @kindex step&
+ @xref{Continuing and Stepping}.
+ 
+ @item stepi
+ @kindex stepi&
+ @xref{Continuing and Stepping}.
+ 
+ @item next
+ @kindex next&
+ @xref{Continuing and Stepping}.
+ 
+ @item continue
+ @kindex continue&
+ @xref{Continuing and Stepping}.
+ 
+ @item finish
+ @kindex finish&
+ @xref{Continuing and Stepping}.
+ 
+ @item until
+ @kindex until&
+ @xref{Continuing and Stepping}.
+ 
+ @end table
+ 
+ Background execution is especially useful in conjunction with non-stop
+ mode for debugging programs with multiple threads; @pxref{Non-Stop Mode}.
+ However, you can also use these commands in the normal all-stop mode with
+ the restriction that you cannot issue another execution command until the
+ previous one finishes.  Examples of commands that are valid in all-stop
+ mode while the program is running include @code{help} and @code{info break}.
+ 
+ You can interrupt your program while it is running in the background by
+ using the @code{interrupt} command.
+ 
+ @table @code
+ @kindex interrupt
+ @item interrupt
+ @itemx interrupt -a
+ 
+ Suspend execution of the running program.  In all-stop mode, 
+ @code{interrupt} stops the whole process, but in non-stop mode, it stops
+ only the current thread.  To stop the whole program in non-stop mode, 
+ use @code{interrupt -a}.
+ @end table
+ 
+ You may need to explicitly enable async mode before you can use background
+ execution commands.  @xref{Maintenance Commands}, for details.  If the
+ target doesn't support async mode, @value{GDBN} issues an error message
+ if you attempt to use the background execution commands.
+ 
+ @node Thread-Specific Breakpoints
+ @subsection Thread-Specific Breakpoints
+ 
  When your program has multiple threads (@pxref{Threads,, Debugging
  Programs with Multiple Threads}), you can choose whether to set
  breakpoints on all threads, or on a particular thread.
*************** breakpoint condition, like this:
*** 4493,4510 ****
  
  @end table
  
! @cindex stopped threads
! @cindex threads, stopped
! Whenever your program stops under @value{GDBN} for any reason,
! @emph{all} threads of execution stop, not just the current thread.  This
! allows you to examine the overall state of the program, including
! switching between threads, without worrying that things may change
! underfoot.
  
  @cindex thread breakpoints and system calls
  @cindex system calls and thread breakpoints
  @cindex premature return from system calls
! There is an unfortunate side effect.  If one thread stops for a
  breakpoint, or for some other reason, and another thread is blocked in a
  system call, then the system call may return prematurely.  This is a
  consequence of the interaction between multiple threads and the signals
--- 4747,4760 ----
  
  @end table
  
! @node Interrupted System Calls
! @subsection Interrupted System Calls 
  
  @cindex thread breakpoints and system calls
  @cindex system calls and thread breakpoints
  @cindex premature return from system calls
! There is an unfortunate side effect when using @value{GDBN} to debug
! multi-threaded programs.  If one thread stops for a
  breakpoint, or for some other reason, and another thread is blocked in a
  system call, then the system call may return prematurely.  This is a
  consequence of the interaction between multiple threads and the signals
*************** monitor certain events such as thread cr
*** 4542,4588 ****
  When such an event happens, a system call in another thread may return
  prematurely, even though your program does not appear to stop.
  
- @cindex continuing threads
- @cindex threads, continuing
- Conversely, whenever you restart the program, @emph{all} threads start
- executing.  @emph{This is true even when single-stepping} with commands
- like @code{step} or @code{next}.
- 
- In particular, @value{GDBN} cannot single-step all threads in lockstep.
- Since thread scheduling is up to your debugging target's operating
- system (not controlled by @value{GDBN}), other threads may
- execute more than one statement while the current thread completes a
- single step.  Moreover, in general other threads stop in the middle of a
- statement, rather than at a clean statement boundary, when the program
- stops.
- 
- You might even find your program stopped in another thread after
- continuing or even single-stepping.  This happens whenever some other
- thread runs into a breakpoint, a signal, or an exception before the
- first thread completes whatever you requested.
- 
- On some OSes, you can lock the OS scheduler and thus allow only a single
- thread to run.
- 
- @table @code
- @item set scheduler-locking @var{mode}
- @cindex scheduler locking mode
- @cindex lock scheduler
- Set the scheduler locking mode.  If it is @code{off}, then there is no
- locking and any thread may run at any time.  If @code{on}, then only the
- current thread may run when the inferior is resumed.  The @code{step}
- mode optimizes for single-stepping.  It stops other threads from
- ``seizing the prompt'' by preempting the current thread while you are
- stepping.  Other threads will only rarely (or never) get a chance to run
- when you step.  They are more likely to run when you @samp{next} over a
- function call, and they are completely free to run when you use commands
- like @samp{continue}, @samp{until}, or @samp{finish}.  However, unless another
- thread hits a breakpoint during its timeslice, they will never steal the
- @value{GDBN} prompt away from the thread that you are debugging.
- 
- @item show scheduler-locking
- Display the current scheduler locking mode.
- @end table
  
  
  @node Stack
--- 4792,4797 ----
*************** compiled with the @samp{-pg} compiler op
*** 23683,23689 ****
  @cindex asynchronous support
  @item maint set linux-async
  @itemx maint show linux-async
! Control the GNU/Linux native asynchronous support of @value{GDBN}.
  
  GNU/Linux native asynchronous support will be disabled until you use
  the @samp{maint set linux-async} command to enable it.
--- 23892,23899 ----
  @cindex asynchronous support
  @item maint set linux-async
  @itemx maint show linux-async
! Control the GNU/Linux native asynchronous support 
! (@pxref{Background Execution}) of @value{GDBN}.
  
  GNU/Linux native asynchronous support will be disabled until you use
  the @samp{maint set linux-async} command to enable it.
*************** the @samp{maint set linux-async} command
*** 23693,23699 ****
  @cindex asynchronous support
  @item maint set remote-async
  @itemx maint show remote-async
! Control the remote asynchronous support of @value{GDBN}.
  
  Remote asynchronous support will be disabled until you use
  the @samp{maint set remote-async} command to enable it.
--- 23903,23910 ----
  @cindex asynchronous support
  @item maint set remote-async
  @itemx maint show remote-async
! Control the remote asynchronous support 
! (@pxref{Background Execution}) of @value{GDBN}.
  
  Remote asynchronous support will be disabled until you use
  the @samp{maint set remote-async} command to enable it.