doc/lispref/threads.texi

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