@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 2012-2019 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Threads
@chapter Threads
@cindex threads
@cindex concurrency

  Emacs Lisp provides a limited form of concurrency, called
@dfn{threads}.  All the threads in a given instance of Emacs share the
same memory.  Concurrency in Emacs Lisp is ``mostly cooperative'',
meaning that Emacs will only switch execution between threads at
well-defined times.  However, the Emacs thread support has been
designed in a way to later allow more fine-grained concurrency, and
correct programs should not rely on cooperative threading.

  Currently, thread switching will occur upon explicit request via
@code{thread-yield}, when waiting for keyboard input or for process
output from asynchronous processes (e.g., during
@code{accept-process-output}), or during blocking operations relating
to threads, such as mutex locking or @code{thread-join}.

  Emacs Lisp provides primitives to create and control threads, and
also to create and control mutexes and condition variables, useful for
thread synchronization.

  While global variables are shared among all Emacs Lisp threads,
local variables are not---a dynamic @code{let} binding is local.  Each
thread also has its own current buffer (@pxref{Current Buffer}) and
its own match data (@pxref{Match Data}).

  Note that @code{let} bindings are treated specially by the Emacs
Lisp implementation.  There is no way to duplicate this unwinding and
rewinding behavior other than by using @code{let}.  For example, a
manual implementation of @code{let} written using
@code{unwind-protect} cannot arrange for variable values to be
thread-specific.

  In the case of lexical bindings (@pxref{Variable Scoping}), a
closure is an object like any other in Emacs Lisp, and bindings in a
closure are shared by any threads invoking the closure.

@menu
* 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
@section Basic Thread Functions

  Threads can be created and waited for.  A thread cannot be exited
directly, but the current thread can be exited implicitly, and other
threads can be signaled.

@defun make-thread function &optional name
Create a new thread of execution which invokes @var{function}.  When
@var{function} returns, the thread exits.

The new thread is created with no local variable bindings in effect.
The new thread's current buffer is inherited from the current thread.

@var{name} can be supplied to give a name to the thread.  The name is
used for debugging and informational purposes only; it has no meaning
to Emacs.  If @var{name} is provided, it must be a string.

This function returns the new thread.
@end defun

@defun threadp object
This function returns @code{t} if @var{object} represents an Emacs
thread, @code{nil} otherwise.
@end defun

@defun thread-join thread
Block until @var{thread} exits, or until the current thread is
signaled.  It returns the result of the @var{thread} function.  If
@var{thread} has already exited, this returns immediately.
@end defun

@defun thread-signal thread error-symbol data
Like @code{signal} (@pxref{Signaling Errors}), but the signal is
delivered in the thread @var{thread}.  If @var{thread} is the current
thread, then this just calls @code{signal} immediately.  Otherwise,
@var{thread} will receive the signal as soon as it becomes current.
If @var{thread} was blocked by a call to @code{mutex-lock},
@code{condition-wait}, or @code{thread-join}; @code{thread-signal}
will unblock it.

If @var{thread} is the main thread, the signal is not propagated
there.  Instead, it is shown as message in the main thread.
@end defun

@defun thread-yield
Yield execution to the next runnable thread.
@end defun

@defun thread-name thread
Return the name of @var{thread}, as specified to @code{make-thread}.
@end defun

@defun thread-live-p thread
Return @code{t} if @var{thread} is alive, or @code{nil} if it is not.
A thread is alive as long as its function is still executing.
@end defun

@defun thread--blocker thread
Return the object that @var{thread} is waiting on.  This function is
primarily intended for debugging, and is given a ``double hyphen''
name to indicate that.

If @var{thread} is blocked in @code{thread-join}, this returns the
thread for which it is waiting.

If @var{thread} is blocked in @code{mutex-lock}, this returns the mutex.

If @var{thread} is blocked in @code{condition-wait}, this returns the
condition variable.

Otherwise, this returns @code{nil}.
@end defun

@defun current-thread
Return the current thread.
@end defun

@defun all-threads
Return a list of all the live thread objects.  A new list is returned
by each invocation.
@end defun

@defvar main-thread
This variable keeps the main thread Emacs is running, or @code{nil} if
Emacs is compiled without thread support.
@end defvar

When code run by a thread signals an error that is unhandled, the
thread exits.  Other threads can access the error form which caused
the thread to exit using the following function.

@defun thread-last-error &optional cleanup
This function returns the last error form recorded when a thread
exited due to an error.  Each thread that exits abnormally overwrites
the form stored by the previous thread's error with a new value, so
only the last one can be accessed.  If @var{cleanup} is
non-@code{nil}, the stored form is reset to @code{nil}.
@end defun

@node Mutexes
@section Mutexes

  A @dfn{mutex} is an exclusive lock.  At any moment, zero or one
threads may own a mutex.  If a thread attempts to acquire a mutex, and
the mutex is already owned by some other thread, then the acquiring
thread will block until the mutex becomes available.

  Emacs Lisp mutexes are of a type called @dfn{recursive}, which means
that a thread can re-acquire a mutex it owns any number of times.  A
mutex keeps a count of how many times it has been acquired, and each
acquisition of a mutex must be paired with a release.  The last
release by a thread of a mutex reverts it to the unowned state,
potentially allowing another thread to acquire the mutex.

@defun mutexp object
This function returns @code{t} if @var{object} represents an Emacs
mutex, @code{nil} otherwise.
@end defun

@defun make-mutex &optional name
Create a new mutex and return it.  If @var{name} is specified, it is a
name given to the mutex.  It must be a string.  The name is for
debugging purposes only; it has no meaning to Emacs.
@end defun

@defun mutex-name mutex
Return the name of @var{mutex}, as specified to @code{make-mutex}.
@end defun

@defun mutex-lock mutex
This will block until this thread acquires @var{mutex}, or until this
thread is signaled using @code{thread-signal}.  If @var{mutex} is
already owned by this thread, this simply returns.
@end defun

@defun mutex-unlock mutex
Release @var{mutex}.  If @var{mutex} is not owned by this thread, this
will signal an error.
@end defun

@defmac with-mutex mutex body@dots{}
This macro is the simplest and safest way to evaluate forms while
holding a mutex.  It acquires @var{mutex}, invokes @var{body}, and
then releases @var{mutex}.  It returns the result of @var{body}.
@end defmac

@node Condition Variables
@section Condition Variables

  A @dfn{condition variable} is a way for a thread to block until some
event occurs.  A thread can wait on a condition variable, to be woken
up when some other thread notifies the condition.

  A condition variable is associated with a mutex and, conceptually,
with some condition.  For proper operation, the mutex must be
acquired, and then a waiting thread must loop, testing the condition
and waiting on the condition variable.  For example:

@example
(with-mutex mutex
  (while (not global-variable)
    (condition-wait cond-var)))
@end example

  The mutex ensures atomicity, and the loop is for robustness---there
may be spurious notifications.

  Similarly, the mutex must be held before notifying the condition.
The typical, and best, approach is to acquire the mutex, make the
changes associated with this condition, and then notify it:

@example
(with-mutex mutex
  (setq global-variable (some-computation))
  (condition-notify cond-var))
@end example

@defun make-condition-variable mutex &optional name
Make a new condition variable associated with @var{mutex}.  If
@var{name} is specified, it is a name given to the condition variable.
It must be a string.  The name is for debugging purposes only; it has
no meaning to Emacs.
@end defun

@defun condition-variable-p object
This function returns @code{t} if @var{object} represents a condition
variable, @code{nil} otherwise.
@end defun

@defun condition-wait cond
Wait for another thread to notify @var{cond}, a condition variable.
This function will block until the condition is notified, or until a
signal is delivered to this thread using @code{thread-signal}.

It is an error to call @code{condition-wait} without holding the
condition's associated mutex.

@code{condition-wait} releases the associated mutex while waiting.
This allows other threads to acquire the mutex in order to notify the
condition.
@end defun

@defun condition-notify cond &optional all
Notify @var{cond}.  The mutex with @var{cond} must be held before
calling this.  Ordinarily a single waiting thread is woken by
@code{condition-notify}; but if @var{all} is not @code{nil}, then all
threads waiting on @var{cond} are notified.

@code{condition-notify} releases the associated mutex while waiting.
This allows other threads to acquire the mutex in order to wait on the
condition.
@c why bother?
@end defun

@defun condition-name cond
Return the name of @var{cond}, as passed to
@code{make-condition-variable}.
@end defun

@defun condition-mutex cond
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} (@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.

@defvar thread-list-refresh-seconds
The @file{*Threads*} buffer will automatically update twice per
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:

@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 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.
@xref{Backtraces}, for a description of backtraces and the other
commands which work on them.

@item s
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.
@end table