From e19ca77534002ae118acb707cf6313df1a908814 Mon Sep 17 00:00:00 2001 From: Gemini Lasswell Date: Tue, 14 Aug 2018 11:08:28 -0700 Subject: [PATCH] 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 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 -- 2.39.2