2008-08-11 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.

2 files changed, 282 insertions, 60 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 68fab78..872fe60 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,15 @@
+2008-08-11  Sandra Loosemore  <sandra@codesourcery.com>
+	    Pedro Alves  <pedro@codesourcery.com>
+
+	* 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.
+
 2008-08-06  Tom Tromey  <tromey@redhat.com>
 
 	* gdb.texinfo (Extending GDB): New chapter.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 891dfb2..72455f3 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -2591,15 +2591,6 @@ Show whether messages will be printed when @value{GDBN} detects that threads
 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.
@@ -4459,6 +4450,268 @@ Program a Signal}.
 @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 such as @samp{[Switching to Thread @var{n}]} 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 prevents other threads 
+from preempting the current thread while you are stepping, so that 
+the focus of debugging does not change unexpectedly.
+Other threads 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, @value{GDBN} does not change
+the current thread 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 background execution
+@cindex asynchronous execution
+@cindex execution, foreground, background and 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 can 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, step}.
+
+@item stepi
+@kindex stepi&
+@xref{Continuing and Stepping, stepi}.
+
+@item next
+@kindex next&
+@xref{Continuing and Stepping, next}.
+
+@item continue
+@kindex continue&
+@xref{Continuing and Stepping, continue}.
+
+@item finish
+@kindex finish&
+@xref{Continuing and Stepping, finish}.
+
+@item until
+@kindex until&
+@xref{Continuing and Stepping, until}.
+
+@end table
+
+Background execution is especially useful in conjunction with non-stop
+mode for debugging programs with multiple threads; see @ref{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.
@@ -4493,18 +4746,14 @@ breakpoint condition, like this:
 
 @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.
+@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.  If one thread stops for a
+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
@@ -4542,47 +4791,6 @@ monitor certain events such as thread creation and thread destruction.
 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
@@ -23849,7 +24057,8 @@ compiled with the @samp{-pg} compiler option.
 @cindex asynchronous support
 @item maint set linux-async
 @itemx maint show linux-async
-Control the GNU/Linux native asynchronous support of @value{GDBN}.
+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.
@@ -23859,7 +24068,8 @@ the @samp{maint set linux-async} command to enable it.
 @cindex asynchronous support
 @item maint set remote-async
 @itemx maint show remote-async
-Control the remote asynchronous support of @value{GDBN}.
+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.