[Emacs-diffs] scratch/list-threads fd3f62c 7/9: Document list-threads and its buffer

[Gemini Lasswell]

branch: scratch/list-threads
commit fd3f62ca1b859d1872d0c03b12befde117e6adb1
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 58a3a91..09491f1 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
@@ -277,3 +278,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 21887f5..ceb9604 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -687,6 +687,9 @@ to signal the main thread, e.g., when they encounter an 
error.
 +++
 *** 'thread-join' returns the result of the finished thread now.
 
++++
+*** 'list-threads' displays the live threads in a tabulated-list buffer.
+
 
 * New Modes and Packages in Emacs 27.1