[Emacs-diffs] emacs/doc/emacs building.texi

[Nick Roberts]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Nick Roberts <nickrob>  09/08/31 03:52:30

Modified files:
        doc/emacs      : building.texi 

Log message:
        (Threads Buffer, Multithreaded Debugging): 
        Re-organise these two sections,

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/emacs/building.texi?cvsroot=emacs&r1=1.23&r2=1.24

Patches:
Index: building.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/emacs/building.texi,v
retrieving revision 1.23
retrieving revision 1.24
diff -u -b -r1.23 -r1.24
--- building.texi       8 Aug 2009 17:00:52 -0000       1.23
+++ building.texi       31 Aug 2009 03:52:29 -0000      1.24
@@ -1016,9 +1016,9 @@
 When @code{gdb-many-windows} is address@hidden, the breakpoints buffer
 shares its window with the threads buffer.  To switch from one to the
 other click with @kbd{Mouse-1} on the relevant button in the header
-line, or press @kbd{TAB} inside that buffer.  When
address@hidden is address@hidden, threads buffer
-is shown in place of breakpoints buffer by default.
+line, or press @kbd{TAB} inside that buffer.  If
address@hidden is address@hidden, the threads
+buffer, rather than the breakpoints buffer, is shown at start up.
 
 @node Threads Buffer
 @subsubsection Threads Buffer
@@ -1054,8 +1054,50 @@
 Show addresses for thread frames in threads buffer.
 @end table
 
-  Several other commands are available in threads buffer to assist in
-  debugging multithreaded programs (@pxref{Multithreaded Debugging}).
+  It’s possible to observe information for several threads
+simultaneously (in addition to buffers which show information for
+currently selected thread) using the following keys from the threads
+buffer.
+
address@hidden @kbd
address@hidden d
address@hidden d @r{(GDB threads buffer)}
address@hidden gdb-display-disassembly-for-thread
+Display disassembly buffer for the thread at current line.
+(@code{gdb-display-disassembly-for-thread})
+
address@hidden f
address@hidden f @r{(GDB threads buffer)}
address@hidden gdb-display-stack-for-thread
+Display stack buffer for the thread at current line.
+(@code{gdb-display-stack-for-thread}).
+
address@hidden l
address@hidden l @r{(GDB threads buffer)}
address@hidden gdb-display-locals-for-thread
+Display locals buffer for the thread at current line.
+(@code{gdb-display-locals-for-thread}).
+
address@hidden r
address@hidden r @r{(GDB threads buffer)}
address@hidden gdb-display-registers-for-thread
+Display registers buffer for the thread at current line.
+(@code{gdb-display-registers-for-thread}).
address@hidden table
+
+Pressing their upper-case counterparts, @kbd{D}, @kbd{F} ,@kbd{L} and
address@hidden displays the corresponding buffer in a new frame.
+
+  When you create a buffer showing information about some specific
+thread, it becomes bound to that thread and keeps showing actual
+information while you debug your program.  Every GDB buffer contains a
+number of thread it shows information for in its mode name.  Thread
+number is also included in the buffer name of bound buffers to prevent
+buffer names clashing.
+
+Further commands are available in the threads buffer which depend on the
+mode of GDB that is used for controlling execution of your program.
+(@pxref{Multithreaded Debugging, Stopping and Starting Multi-threaded 
Programs}).
 
 @node Stack Buffer
 @subsubsection Stack Buffer
@@ -1200,26 +1242,36 @@
 screen Emacs frame.
 
 @node Multithreaded Debugging
address@hidden Multithreaded Debugging
address@hidden Stopping and Starting Multi-threaded Programs
 @cindex Multithreaded debugging in GDB
 
-  Features described in this node are supported only by GDB 7.0.
address@hidden All-stop Debugging
+
+In all-stop mode, whenever your program stops, @emph{all} threads of
+execution stop.  Likewise, whenever you restart the program, all
+threads start executing.  @xref{All-Stop Mode, , All-Stop Mode, gdb,
+The GNU debugger}.  You can enable this behaviour in Emacs by setting
address@hidden to @code{nil} before starting a debugging
+session.
 
 @subsubheading Non-stop Debugging
 @cindex Non-stop debugging in GDB
 
-  For some multithreaded targets, GDB allows debugging in
address@hidden mode}.  If non-stop mode is activated, when one thread
-stops, the rest continue to execute, as opposed to traditional
address@hidden mode}, in which stopping of one thread causes @emph{all}
-threads to stop. @xref{Non-Stop Mode, , Non-Stop Mode, gdb, The GNU
-debugger}.
+For some multi-threaded targets, GDB supports a further mode of
+operation in which you can examine stopped program threads in the
+debugger while other threads continue to execute freely.
address@hidden Mode, , Non-Stop Mode, gdb, The GNU debugger}.
+This is referred to as @dfn{non-stop} mode.
+
+Versions of GDB prior to 7.0 do not support non-stop mode and it does
+not work on all targets.  In such cases, Emacs uses all-stop mode
+regardless of the value of @code{gdb-non-stop-setting}.
 
 @vindex gdb-non-stop-setting
-To activate non-stop debugging in Emacs, set
address@hidden variable to address@hidden  Note that GDB
-debugging session needs to be restarted for change of this setting to
-take effect.
+If the variable @code{gdb-non-stop-setting} is address@hidden (the
+default value), Emacs tries to start GDB in non-stop mode.  Note that
+GDB debugging session needs to be restarted for change of this setting
+to take effect.
 
 @vindex gdb-switch-when-another-stopped
 When a thread stops in non-stop mode, Emacs automatically switches to
@@ -1228,13 +1280,13 @@
 @code{gdb-switch-when-another-stopped} to @code{nil} to prevent this.
 
 @vindex gdb-switch-reasons
-Emacs can decide whether or not to switch to stopped thread depending
-on the reason which caused the stop.  Customize
+Emacs can decide whether or not to switch to the stopped thread
+depending on the reason which caused the stop.  Customize
 @code{gdb-switch-reasons} to select stop reasons which make Emacs
 switch thread.
 
 @vindex gdb-stopped-hooks
address@hidden hook variable allows you to execute your
+The variable @code{gdb-stopped-hooks} allows you to execute your
 functions whenever some thread stops.
 
   In non-stop mode, you can switch between different modes for GUD
@@ -1244,96 +1296,32 @@
 @table @dfn
 @item Non-stop/A
 
-When @code{gdb-gud-control-all-threads} is @code{t} (that’s default),
-interruption & continuation commands apply to all threads, so you can
-halt or continue all your threads with one command
-(@code{gud-stop-subjob} and @code{gud-cont}, respectively).  @samp{Go}
-button is shown on the toolbar when at least one thread is stopped,
-whereas @samp{Stop} button is shown when at least one thread is
-running.
+When @code{gdb-gud-control-all-threads} is @code{t} (the default
+value), interruption and continuation commands apply to all threads,
+so you can halt or continue all your threads with one command using
address@hidden and @code{gud-cont}, respectively.  The
address@hidden button is shown on the toolbar when at least one thread is
+stopped, whereas @samp{Stop} button is shown when at least one thread
+is running.
 
 @item Non-stop/T
 
-When @code{gdb-gud-control-all-threads} is @code{nil}, only current
-thread is stopped/continued.  @samp{Go} and @samp{Stop} buttons on
-the GUD toolbar are shown depending on the state of current thread.
+When @code{gdb-gud-control-all-threads} is @code{nil}, only the
+current thread is stopped/continued.  @samp{Go} and @samp{Stop}
+buttons on the GUD toolbar are shown depending on the state of current
+thread.
 @end table
 
 You can change the current value of @code{gdb-gud-control-all-threads}
-from @samp{GUD->GDB-MI} menu.
+from the tool bar or from @samp{GUD->GDB-MI} menu.
 
-  Stepping commands always apply to current thread.
-
address@hidden Observing Several Threads Simultaneously
address@hidden Observing several threads simultaneously in GDB
-
-  It’s possible to observe information for several threads
-simultaneously (in addition to buffers which show information for
-currently selected thread) using the following keys from the threads
-buffer.
-
address@hidden @key
address@hidden d
address@hidden d @r{(GDB threads buffer)}
address@hidden gdb-display-disassembly-for-thread
-Display disassembly buffer for the thread at current line.
-(@code{gdb-display-disassembly-for-thread})
-
address@hidden f
address@hidden f @r{(GDB threads buffer)}
address@hidden gdb-display-stack-for-thread
-Display stack buffer for the thread at current line.
-(@code{gdb-display-stack-for-thread}).
-
address@hidden l
address@hidden l @r{(GDB threads buffer)}
address@hidden gdb-display-locals-for-thread
-Display locals buffer for the thread at current line.
-(@code{gdb-display-locals-for-thread}).
-
address@hidden r
address@hidden r @r{(GDB threads buffer)}
address@hidden gdb-display-registers-for-thread
-Display registers buffer for the thread at current line.
-(@code{gdb-display-registers-for-thread}).
-
address@hidden D
address@hidden D @r{(GDB threads buffer)}
address@hidden gdb-frame-disassembly-for-thread
-Display a new frame with disassembly buffer for the thread at current
-line. (@code{gdb-frame-disassembly-for-thread}).
-
address@hidden F
address@hidden F @r{(GDB threads buffer)}
address@hidden gdb-frame-stack-for-thread
-Display a new frame with stack buffer for the thread at current line.
-(@code{gdb-frame-stack-for-thread}).
-
address@hidden L
address@hidden L @r{(GDB threads buffer)}
address@hidden gdb-frame-locals-for-thread
-Display a new frame with locals buffer for the thread at current line.
-(@code{gdb-frame-locals-for-thread}).
-
address@hidden R
address@hidden R @r{(GDB threads buffer)}
address@hidden gdb-frame-registers-for-thread
-Display a new frame with registers buffer for the thread at current
-line. (@code{gdb-frame-registers-for-thread}).
address@hidden table
-
-  When you create a buffer showing information about some specific
-thread, it becomes bound to that thread and keeps showing actual
-information while you debug your program.  Every GDB buffer contains a
-number of thread it shows information for in its mode name.  Thread
-number is also included in the buffer name of bound buffers to prevent
-buffer names clashing.
+  Stepping commands always apply to the current thread.
 
 @subsubheading Fine Thread Control
 
   In non-stop mode, you can interrupt/continue your threads without
-selecting them.  Hitting @key{i} in threads buffer interrupts thread
-under point, @key{c} continues it, @key{s} steps through.  More such
+selecting them.  Hitting @kbd{i} in threads buffer interrupts thread
+under point, @kbd{c} continues it, @kbd{s} steps through.  More such
 commands may be added in the future.
 
 Combined with creating bound buffers for any thread, this allows you