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.
This commit is contained in:
Sandra Loosemore
parent
8ab3d180b1
commit
0606b73b11
2 changed files with 282 additions and 60 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue