doc/lispref/threads.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the GNU Emacs Lisp Reference Manual.
   3 @c Copyright (C) 2012-2018 Free Software Foundation, Inc.
   4 @c See the file elisp.texi for copying conditions.
   5 @node Threads
   6 @chapter Threads
   7 @cindex threads
   8 @cindex concurrency
   9
  10   Emacs Lisp provides a limited form of concurrency, called
  11 @dfn{threads}.  All the threads in a given instance of Emacs share the
  12 same memory.  Concurrency in Emacs Lisp is ``mostly cooperative'',
  13 meaning that Emacs will only switch execution between threads at
  14 well-defined times.  However, the Emacs thread support has been
  15 designed in a way to later allow more fine-grained concurrency, and
  16 correct programs should not rely on cooperative threading.
  17
  18   Currently, thread switching will occur upon explicit request via
  19 @code{thread-yield}, when waiting for keyboard input or for process
  20 output (e.g., during @code{accept-process-output}), or during blocking
  21 operations relating to threads, such as mutex locking or
  22 @code{thread-join}.
  23
  24   Emacs Lisp provides primitives to create and control threads, and
  25 also to create and control mutexes and condition variables, useful for
  26 thread synchronization.
  27
  28   While global variables are shared among all Emacs Lisp threads,
  29 local variables are not---a dynamic @code{let} binding is local.  Each
  30 thread also has its own current buffer (@pxref{Current Buffer}) and
  31 its own match data (@pxref{Match Data}).
  32
  33   Note that @code{let} bindings are treated specially by the Emacs
  34 Lisp implementation.  There is no way to duplicate this unwinding and
  35 rewinding behavior other than by using @code{let}.  For example, a
  36 manual implementation of @code{let} written using
  37 @code{unwind-protect} cannot arrange for variable values to be
  38 thread-specific.
  39
  40   In the case of lexical bindings (@pxref{Variable Scoping}), a
  41 closure is an object like any other in Emacs Lisp, and bindings in a
  42 closure are shared by any threads invoking the closure.
  43
  44 @menu
  45 * Basic Thread Functions::      Basic thread functions.
  46 * Mutexes::                     Mutexes allow exclusive access to data.
  47 * Condition Variables::         Inter-thread events.
  48 @end menu
  49
  50 @node Basic Thread Functions
  51 @section Basic Thread Functions
  52
  53   Threads can be created and waited for.  A thread cannot be exited
  54 directly, but the current thread can be exited implicitly, and other
  55 threads can be signaled.
  56
  57 @defun make-thread function &optional name
  58 Create a new thread of execution which invokes @var{function}.  When
  59 @var{function} returns, the thread exits.
  60
  61 The new thread is created with no local variable bindings in effect.
  62 The new thread's current buffer is inherited from the current thread.
  63
  64 @var{name} can be supplied to give a name to the thread.  The name is
  65 used for debugging and informational purposes only; it has no meaning
  66 to Emacs.  If @var{name} is provided, it must be a string.
  67
  68 This function returns the new thread.
  69 @end defun
  70
  71 @defun threadp object
  72 This function returns @code{t} if @var{object} represents an Emacs
  73 thread, @code{nil} otherwise.
  74 @end defun
  75
  76 @defun thread-join thread
  77 Block until @var{thread} exits, or until the current thread is
  78 signaled.  If @var{thread} has already exited, this returns
  79 immediately.
  80 @end defun
  81
  82 @defun thread-signal thread error-symbol data
  83 Like @code{signal} (@pxref{Signaling Errors}), but the signal is
  84 delivered in the thread @var{thread}.  If @var{thread} is the current
  85 thread, then this just calls @code{signal} immediately.  Otherwise,
  86 @var{thread} will receive the signal as soon as it becomes current.
  87 If @var{thread} was blocked by a call to @code{mutex-lock},
  88 @code{condition-wait}, or @code{thread-join}; @code{thread-signal}
  89 will unblock it.
  90 @end defun
  91
  92 @defun thread-yield
  93 Yield execution to the next runnable thread.
  94 @end defun
  95
  96 @defun thread-name thread
  97 Return the name of @var{thread}, as specified to @code{make-thread}.
  98 @end defun
  99
 100 @defun thread-alive-p thread
 101 Return @code{t} if @var{thread} is alive, or @code{nil} if it is not.
 102 A thread is alive as long as its function is still executing.
 103 @end defun
 104
 105 @defun thread--blocker thread
 106 Return the object that @var{thread} is waiting on.  This function is
 107 primarily intended for debugging, and is given a ``double hyphen''
 108 name to indicate that.
 109
 110 If @var{thread} is blocked in @code{thread-join}, this returns the
 111 thread for which it is waiting.
 112
 113 If @var{thread} is blocked in @code{mutex-lock}, this returns the mutex.
 114
 115 If @var{thread} is blocked in @code{condition-wait}, this returns the
 116 condition variable.
 117
 118 Otherwise, this returns @code{nil}.
 119 @end defun
 120
 121 @defun current-thread
 122 Return the current thread.
 123 @end defun
 124
 125 @defun all-threads
 126 Return a list of all the live thread objects.  A new list is returned
 127 by each invocation.
 128 @end defun
 129
 130 When code run by a thread signals an error that is unhandled, the
 131 thread exits.  Other threads can access the error form which caused
 132 the thread to exit using the following function.
 133
 134 @defun thread-last-error
 135 This function returns the last error form recorded when a thread
 136 exited due to an error.  Each thread that exits abnormally overwrites
 137 the form stored by the previous thread's error with a new value, so
 138 only the last one can be accessed.
 139 @end defun
 140
 141 @node Mutexes
 142 @section Mutexes
 143
 144   A @dfn{mutex} is an exclusive lock.  At any moment, zero or one
 145 threads may own a mutex.  If a thread attempts to acquire a mutex, and
 146 the mutex is already owned by some other thread, then the acquiring
 147 thread will block until the mutex becomes available.
 148
 149   Emacs Lisp mutexes are of a type called @dfn{recursive}, which means
 150 that a thread can re-acquire a mutex it owns any number of times.  A
 151 mutex keeps a count of how many times it has been acquired, and each
 152 acquisition of a mutex must be paired with a release.  The last
 153 release by a thread of a mutex reverts it to the unowned state,
 154 potentially allowing another thread to acquire the mutex.
 155
 156 @defun mutexp object
 157 This function returns @code{t} if @var{object} represents an Emacs
 158 mutex, @code{nil} otherwise.
 159 @end defun
 160
 161 @defun make-mutex &optional name
 162 Create a new mutex and return it.  If @var{name} is specified, it is a
 163 name given to the mutex.  It must be a string.  The name is for
 164 debugging purposes only; it has no meaning to Emacs.
 165 @end defun
 166
 167 @defun mutex-name mutex
 168 Return the name of @var{mutex}, as specified to @code{make-mutex}.
 169 @end defun
 170
 171 @defun mutex-lock mutex
 172 This will block until this thread acquires @var{mutex}, or until this
 173 thread is signaled using @code{thread-signal}.  If @var{mutex} is
 174 already owned by this thread, this simply returns.
 175 @end defun
 176
 177 @defun mutex-unlock mutex
 178 Release @var{mutex}.  If @var{mutex} is not owned by this thread, this
 179 will signal an error.
 180 @end defun
 181
 182 @defmac with-mutex mutex body@dots{}
 183 This macro is the simplest and safest way to evaluate forms while
 184 holding a mutex.  It acquires @var{mutex}, invokes @var{body}, and
 185 then releases @var{mutex}.  It returns the result of @var{body}.
 186 @end defmac
 187
 188 @node Condition Variables
 189 @section Condition Variables
 190
 191   A @dfn{condition variable} is a way for a thread to block until some
 192 event occurs.  A thread can wait on a condition variable, to be woken
 193 up when some other thread notifies the condition.
 194
 195   A condition variable is associated with a mutex and, conceptually,
 196 with some condition.  For proper operation, the mutex must be
 197 acquired, and then a waiting thread must loop, testing the condition
 198 and waiting on the condition variable.  For example:
 199
 200 @example
 201 (with-mutex mutex
 202   (while (not global-variable)
 203     (condition-wait cond-var)))
 204 @end example
 205
 206   The mutex ensures atomicity, and the loop is for robustness---there
 207 may be spurious notifications.
 208
 209   Similarly, the mutex must be held before notifying the condition.
 210 The typical, and best, approach is to acquire the mutex, make the
 211 changes associated with this condition, and then notify it:
 212
 213 @example
 214 (with-mutex mutex
 215   (setq global-variable (some-computation))
 216   (condition-notify cond-var))
 217 @end example
 218
 219 @defun make-condition-variable mutex &optional name
 220 Make a new condition variable associated with @var{mutex}.  If
 221 @var{name} is specified, it is a name given to the condition variable.
 222 It must be a string.  The name is for debugging purposes only; it has
 223 no meaning to Emacs.
 224 @end defun
 225
 226 @defun condition-variable-p object
 227 This function returns @code{t} if @var{object} represents a condition
 228 variable, @code{nil} otherwise.
 229 @end defun
 230
 231 @defun condition-wait cond
 232 Wait for another thread to notify @var{cond}, a condition variable.
 233 This function will block until the condition is notified, or until a
 234 signal is delivered to this thread using @code{thread-signal}.
 235
 236 It is an error to call @code{condition-wait} without holding the
 237 condition's associated mutex.
 238
 239 @code{condition-wait} releases the associated mutex while waiting.
 240 This allows other threads to acquire the mutex in order to notify the
 241 condition.
 242 @end defun
 243
 244 @defun condition-notify cond &optional all
 245 Notify @var{cond}.  The mutex with @var{cond} must be held before
 246 calling this.  Ordinarily a single waiting thread is woken by
 247 @code{condition-notify}; but if @var{all} is not @code{nil}, then all
 248 threads waiting on @var{cond} are notified.
 249
 250 @code{condition-notify} releases the associated mutex while waiting.
 251 This allows other threads to acquire the mutex in order to wait on the
 252 condition.
 253 @c why bother?
 254 @end defun
 255
 256 @defun condition-name cond
 257 Return the name of @var{cond}, as passed to
 258 @code{make-condition-variable}.
 259 @end defun
 260
 261 @defun condition-mutex cond
 262 Return the mutex associated with @var{cond}.  Note that the associated
 263 mutex cannot be changed.
 264 @end defun