Document list-threads and its buffer

* doc/lispref/threads.texi (Threads): Add menu item.
(The Thread List): New node.
* doc/lispref/elisp.texi (Top): Add menu item.

3 files changed, 51 insertions, 0 deletions

diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 1d861fbced4..0a445a36bd3 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1346,6 +1346,7 @@ Threads
 * Basic Thread Functions::  Basic thread functions.
 * Mutexes::                 Mutexes allow exclusive access to data.
 * Condition Variables::     Inter-thread events.
+* The Thread List::         Show the active threads.
 
 Processes
 
diff --git a/doc/lispref/threads.texi b/doc/lispref/threads.texi
index 9cdeb798c1d..a4a1af30857 100644
--- a/doc/lispref/threads.texi
+++ b/doc/lispref/threads.texi
@@ -45,6 +45,7 @@ closure are shared by any threads invoking the closure.
 * Basic Thread Functions::      Basic thread functions.
 * Mutexes::                     Mutexes allow exclusive access to data.
 * Condition Variables::         Inter-thread events.
+* The Thread List::             Show the active threads.
 @end menu
 
 @node Basic Thread Functions
@@ -271,3 +272,49 @@ Return the name of @var{cond}, as passed to
 Return the mutex associated with @var{cond}.  Note that the associated
 mutex cannot be changed.
 @end defun
+
+@node The Thread List
+@section The Thread List
+
+@cindex thread list
+@cindex list of threads
+@findex list-threads
+The @code{list-threads} command lists all the currently alive threads.
+In the resulting buffer, each thread is identified either by the name
+passed to @code{make-thread}, or by its unique internal identifier if
+it was not created with a name.  The status of each thread at the time
+of the creation or last update of the buffer is shown, in addition to
+the object the thread was blocked on at the time, if it was blocked.
+
+@vindex thread-list-refresh-seconds
+The @file{*Threads*} buffer will automatically update twice per
+second.  To make the refresh rate faster or slower, customize
+@code{thread-list-refresh-seconds}.
+
+Here are the commands available in the thread list buffer:
+
+@table @kbd
+
+@cindex backtrace of thread
+@cindex thread backtrace
+@item b
+Show a backtrace of the thread at point.  This will show where in its
+code the thread had yielded or was blocked at the moment you pressed
+@kbd{b}.  Be aware that by the time you see the backtrace, the thread
+may have resumed execution, and be in a different section of code, or
+be completed.
+
+You may use @kbd{g} in the thread's backtrace buffer to get an updated
+backtrace, as backtrace buffers do not automatically update.
+@xref{Backtraces}, for a description of backtraces and the other
+commands which work on them.
+
+@item s
+Send a signal to the thread at point.  After @kbd{s}, type @kbd{q} to
+send a quit signal or @kbd{e} to send an error signal.  Only do this
+if you understand how to restart the target thread, because your Emacs
+session may behave incorrectly if necessary threads are killed.
+
+@item g
+Update the list of threads and their statuses.
+@end table
diff --git a/etc/NEWS b/etc/NEWS
index 61b6d4e0e2b..2e4ed5ddf9f 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -737,6 +737,9 @@ Instead, error messages are just printed in the main thread.
 ---
 *** 'thread-alive-p' is now obsolete, use 'thread-live-p' instead.
 
++++
+*** 'list-threads' displays the live threads in a tabulated-list buffer.
+
 ---
 ** thingatpt.el supports a new "thing" called 'uuid'.
 A symbol 'uuid' can be passed to thing-at-point and it returns the