doc/lispref/threads.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the GNU Emacs Lisp Reference Manual.
   3 @c Copyright (C) 2012, 2013
   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, and is given a ``double hyphen''
 107 name to indicate that.
 108
 109 If @var{thread} is blocked in @code{thread-join}, this returns the
 110 thread for which it is waiting.
 111
 112 If @var{thread} is blocked in @code{mutex-lock}, this returns the mutex.
 113
 114 If @var{thread} is blocked in @code{condition-wait}, this returns the
 115 condition variable.
 116
 117 Otherwise, this returns @code{nil}.
 118 @end defun
 119
 120 @defun current-thread
 121 Return the current thread.
 122 @end defun
 123
 124 @defun all-threads
 125 Return a list of all the live thread objects.  A new list is returned
 126 by each invocation.
 127 @end defun
 128
 129 @node Mutexes
 130 @section Mutexes
 131
 132   A @dfn{mutex} is an exclusive lock.  At any moment, zero or one
 133 threads may own a mutex.  If a thread attempts to acquire a mutex, and
 134 the mutex is already owned by some other thread, then the acquiring
 135 thread will block until the mutex becomes available.
 136
 137   Emacs Lisp mutexes are of a type called @dfn{recursive}, which means
 138 that a thread can re-acquire a mutex it owns any number of times.  A
 139 mutex keeps a count of how many times it has been acquired, and each
 140 acquisition of a mutex must be paired with a release.  The last
 141 release by a thread of a mutex reverts it to the unowned state,
 142 potentially allowing another thread to acquire the mutex.
 143
 144 @defun mutexp object
 145 This function returns @code{t} if @var{object} represents an Emacs
 146 mutex, @code{nil} otherwise.
 147 @end defun
 148
 149 @defun make-mutex &optional name
 150 Create a new mutex and return it.  If @var{name} is specified, it is a
 151 name given to the mutex.  It must be a string.  The name is for
 152 debugging purposes only; it has no meaning to Emacs.
 153 @end defun
 154
 155 @defun mutex-name mutex
 156 Return the name of @var{mutex}, as specified to @code{make-mutex}.
 157 @end defun
 158
 159 @defun mutex-lock mutex
 160 This will block until this thread acquires @var{mutex}, or until this
 161 thread is signaled using @code{thread-signal}.  If @var{mutex} is
 162 already owned by this thread, this simply returns.
 163 @end defun
 164
 165 @defun mutex-unlock mutex
 166 Release @var{mutex}.  If @var{mutex} is not owned by this thread, this
 167 will signal an error.
 168 @end defun
 169
 170 @defmac with-mutex mutex body@dots{}
 171 This macro is the simplest and safest way to evaluate forms while
 172 holding a mutex.  It acquires @var{mutex}, invokes @var{body}, and
 173 then releases @var{mutex}.  It returns the result of @var{body}.
 174 @end defmac
 175
 176 @node Condition Variables
 177 @section Condition Variables
 178
 179   A @dfn{condition variable} is a way for a thread to block until some
 180 event occurs.  A thread can wait on a condition variable, to be woken
 181 up when some other thread notifies the condition.
 182
 183   A condition variable is associated with a mutex and, conceptually,
 184 with some condition.  For proper operation, the mutex must be
 185 acquired, and then a waiting thread must loop, testing the condition
 186 and waiting on the condition variable.  For example:
 187
 188 @example
 189 (with-mutex mutex
 190   (while (not global-variable)
 191     (condition-wait cond-var)))
 192 @end example
 193
 194   The mutex ensures atomicity, and the loop is for robustness---there
 195 may be spurious notifications.  Emacs Lisp provides a macro,
 196 @code{until-condition}, to do this automatically.
 197
 198   Similarly, the mutex must be held before notifying the condition.
 199 The typical, and best, approach is to acquire the mutex, make the
 200 changes associated with this condition, and then signal it:
 201
 202 @example
 203 (with-mutex mutex
 204   (setq global-variable (some-computation))
 205   (condition-signal cond-var))
 206 @end example
 207
 208 @defun make-condition-variable mutex &optional name
 209 Make a new condition variable associated with @var{mutex}.  If
 210 @var{name} is specified, it is a name given to the condition variable.
 211 It must be a string.  The name is for debugging purposes only; it has
 212 no meaning to Emacs.
 213 @end defun
 214
 215 @defun condition-variable-p object
 216 This function returns @code{t} if @var{object} represents a condition
 217 variable, @code{nil} otherwise.
 218 @end defun
 219
 220 @defun condition-wait cond
 221 Wait for another thread to notify @var{cond}, a condition variable.
 222 This function will block until the condition is notified, or until a
 223 signal is delivered to this thread using @code{thread-signal}.
 224
 225 It is an error to call @code{condition-wait} without holding the
 226 condition's associated mutex.
 227
 228 @code{condition-wait} releases the associated mutex while waiting.
 229 This allows other threads to acquire the mutex in order to notify the
 230 condition.
 231 @end defun
 232
 233 @defun condition-notify cond &optional all
 234 Notify @var{cond}.  The mutex with @var{cond} must be held before
 235 calling this.  Ordinarily a single waiting thread is woken by
 236 @code{condition-notify}; but if @var{all} is not @code{nil}, then all
 237 threads waiting on @var{cond} are notified.
 238
 239 @code{condition-notify} releases the associated mutex while waiting.
 240 This allows other threads to acquire the mutex in order to wait on the
 241 condition.
 242 @c why bother?
 243 @end defun
 244
 245 @defun condition-name cond
 246 Return the name of @var{cond}, as passed to
 247 @code{make-condition-variable}.
 248 @end defun
 249
 250 @defun condition-mutex cond
 251 Return the mutex associated with @var{cond}.  Note that the associated
 252 mutex cannot be changed.
 253 @end defun
 254
 255 @defmac until-condition test cond
 256 Acquire the mutex associated with @var{cond}, and then loop, invoking
 257 the form @var{test}.  If @var{test} evaluates to @code{nil}, invoke
 258 @code{condition-wait} on @var{cond}.
 259 @end defmac