From: Gemini Lasswell Date: Wed, 5 Sep 2018 23:55:45 +0000 (-0700) Subject: Improve documentation of thread list buffer X-Git-Tag: emacs-27.0.90~4449^2~1 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=8adc0e518fe36b6251d79ac61b6de9d4766a6afd;p=emacs.git Improve documentation of thread list buffer * doc/lispref/threads.texi (The Thread List): Cross-reference 'Basic Thread Functions'. Use defvar for thread-list-refresh-seconds. Improve descriptions of the backtrace and signal commands. --- diff --git a/doc/lispref/threads.texi b/doc/lispref/threads.texi index a4a1af30857..c9d5f790485 100644 --- a/doc/lispref/threads.texi +++ b/doc/lispref/threads.texi @@ -281,15 +281,17 @@ mutex cannot be changed. @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. +passed to @code{make-thread} (@pxref{Basic Thread Functions}), 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 +@defvar 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}. +second. You can make the refresh rate faster or slower by customizing +this variable. +@end defvar Here are the commands available in the thread list buffer: @@ -300,9 +302,9 @@ Here are the commands available in the thread list buffer: @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. +@kbd{b}. Be aware that the backtrace is a snapshot; the thread could +have meanwhile resumed execution, and be in a different state, or +could have exited. You may use @kbd{g} in the thread's backtrace buffer to get an updated backtrace, as backtrace buffers do not automatically update. @@ -310,10 +312,12 @@ backtrace, as backtrace buffers do not automatically update. 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. +Signal the thread at point. After @kbd{s}, type @kbd{q} to send a +quit signal or @kbd{e} to send an error signal. Threads may implement +handling of signals, but the default behavior is to exit on any +signal. Therefore you should only use this command 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. diff --git a/etc/NEWS b/etc/NEWS index 2e4ed5ddf9f..ff65a5520d5 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -738,7 +738,11 @@ 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. +*** New command 'list-threads' shows Lisp threads. +See the current list of live threads in a tabulated-list buffer which +automatically updates. In the buffer, you can use 's q' or 's e' to +signal a thread with quit or error respectively, or get a snapshot +backtrace with 'b'. --- ** thingatpt.el supports a new "thing" called 'uuid'.