[Emacs-diffs] master e19ca77 07/12: Document list-threads and its buffer

[Gemini Lasswell]

branch: master
commit e19ca77534002ae118acb707cf6313df1a908814
Author: Gemini Lasswell <address@hidden>
Commit: Gemini Lasswell <address@hidden>

    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.
---
 doc/lispref/elisp.texi   |  1 +
 doc/lispref/threads.texi | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 etc/NEWS                 |  3 +++
 3 files changed, 51 insertions(+)

diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 1d861fb..0a445a3 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 9cdeb79..a4a1af3 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
+
address@hidden The Thread List
address@hidden The Thread List
+
address@hidden thread list
address@hidden list of threads
address@hidden 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.
+
address@hidden thread-list-refresh-seconds
+The @file{*Threads*} buffer will automatically update twice per
+second.  To make the refresh rate faster or slower, customize
address@hidden
+
+Here are the commands available in the thread list buffer:
+
address@hidden @kbd
+
address@hidden backtrace of thread
address@hidden thread backtrace
address@hidden 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
address@hidden  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.
address@hidden, for a description of backtraces and the other
+commands which work on them.
+
address@hidden 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.
+
address@hidden g
+Update the list of threads and their statuses.
address@hidden table
diff --git a/etc/NEWS b/etc/NEWS
index 61b6d4e..2e4ed5d 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