threads.texi 9.36 KB
Newer Older
1 2
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
Paul Eggert's avatar
Paul Eggert committed
@c Copyright (C) 2012-2018 Free Software Foundation, Inc.
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
@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 (e.g., during @code{accept-process-output}), or during blocking
operations relating to threads, such as mutex locking or

  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,
Tom Tromey's avatar
Tom Tromey committed
local variables are not---a dynamic @code{let} binding is local.  Each
30 31
thread also has its own current buffer (@pxref{Current Buffer}) and
its own match data (@pxref{Match Data}).

33 34 35 36 37 38 39
  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

40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60
  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.

* Basic Thread Functions::      Basic thread functions.
* Mutexes::                     Mutexes allow exclusive access to data.
* Condition Variables::         Inter-thread events.
@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.

Tom Tromey's avatar
Tom Tromey committed
61 62 63
The new thread is created with no local variable bindings in effect.
The new thread's current buffer is inherited from the current thread.

64 65 66 67 68 69 70 71 72 73 74 75 76
@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
Tom Tromey's avatar
Tom Tromey committed
77 78 79
Block until @var{thread} exits, or until the current thread is
signaled.  If @var{thread} has already exited, this returns
80 81 82 83 84
@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
85 86 87 88 89
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.
90 91 92 93 94 95 96 97 98 99
@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
101 102 103 104
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
107 108
primarily intended for debugging, and is given a ``double hyphen''
name to indicate that.
109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129

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

130 131 132 133 134 135 136 137 138 139 140
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
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.
@end defun

141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206
@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:

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

  The mutex ensures atomicity, and the loop is for robustness---there
Tom Tromey's avatar
Tom Tromey committed
may be spurious notifications.
208 209 210

  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:
212 213 214 215

(with-mutex mutex
  (setq global-variable (some-computation))
  (condition-notify cond-var))
217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264
@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
@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
@c why bother?
@end defun

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

@defun condition-mutex cond
Return the mutex associated with @var{cond}.  Note that the associated
mutex cannot be changed.
@end defun