src/default-implementations.lisp

   1 (in-package #:bordeaux-threads)
   2
   3 ;;; Helper macros
   4
   5 (defmacro defdfun (name args doc &body body)
   6   (let ((docstring (gensym "DOCSTRING")))
   7     `(progn
   8        (when (not (fboundp ',name))
   9          (defun ,name ,args ,@body))
  10        (let ((,docstring (documentation ',name 'function)))
  11          (setf (documentation ',name 'function)
  12                (if ,docstring
  13                    (format nil "~a~@[~%~%~a~]" ,doc ,docstring)
  14                    ,doc))))))
  15
  16 (defmacro defdmacro (name args doc &body body)
  17   (let ((docstring (gensym "DOCSTRING")))
  18     `(progn
  19        (when (not (fboundp ',name))
  20          (defmacro ,name ,args ,@body))
  21        (let ((,docstring (documentation ',name 'function)))
  22          (setf (documentation ',name 'function)
  23                (if ,docstring
  24                    (format nil "~a~@[~%~%~a~]" ,doc ,docstring)
  25                    ,doc))))))
  26
  27 ;;; Thread Creation
  28
  29 (defdfun make-thread (function &key name)
  30   "Creates and returns a thread named NAME, which will call the
  31   function FUNCTION with no arguments: when FUNCTION returns, the
  32   thread terminates. NAME defaults to NIL if unsupplied.
  33
  34   On systems that do not support multi-threading, MAKE-THREAD will
  35   signal an error.
  36
  37   The interaction between threads and dynamic variables is in some
  38   cases complex, and depends on whether the variable has only a global
  39   binding (as established by e.g. DEFVAR/DEFPARAMETER/top-level SETQ)
  40   or has been bound locally (e.g. with LET or LET*) in the calling
  41   thread.
  42
  43   - Global bindings are shared between threads: the initial value of a
  44     global variable in the new thread will be the same as in the
  45     parent, and an assignment to such a variable in any thread will be
  46     visible to all threads in which the global binding is visible.
  47
  48   - Local bindings are local to the thread they are introduced in,
  49     except that
  50
  51   - Local bindings in the the caller of MAKE-THREAD may or may not be
  52     shared with the new thread that it creates: this is
  53     implementation-defined. Portable code should not depend on
  54     particular behaviour in this case, nor should it assign to such
  55     variables without first rebinding them in the new thread."
  56   (declare (ignore function name))
  57   (error (make-threading-support-error)))
  58
  59 (defdfun current-thread ()
  60   "Returns the thread object for the calling
  61   thread. This is the same kind of object as would be returned by
  62   MAKE-THREAD."
  63   nil)
  64
  65 (defdfun threadp (object)
  66   "Returns true if object is a thread, otherwise NIL."
  67   (declare (ignore object))
  68   nil)
  69
  70 (defdfun thread-name (thread)
  71   "Returns the name of the thread, as supplied to MAKE-THREAD."
  72   (declare (ignore thread))
  73   "Main thread")
  74
  75 ;;; Resource contention: locks and recursive locks
  76
  77 (defdfun make-lock (&optional name)
  78   "Creates a lock (a mutex) whose name is NAME. If the system does not
  79   support multiple threads this will still return some object, but it
  80   may not be used for very much."
  81   ;; In CLIM-SYS this is a freshly consed list (NIL). I don't know if
  82   ;; there's some good reason it should be said structure or that it
  83   ;; be freshly consed - EQ comparison of locks?
  84   (declare (ignore name))
  85   (list nil))
  86
  87 (defdfun acquire-lock (lock &optional wait-p)
  88   "Acquire the lock LOCK for the calling thread.
  89   WAIT-P governs what happens if the lock is not available: if WAIT-P
  90   is true, the calling thread will wait until the lock is available
  91   and then acquire it; if WAIT-P is NIL, ACQUIRE-LOCK will return
  92   immediately. ACQUIRE-LOCK returns true if the lock was acquired and
  93   NIL otherwise.
  94
  95   This specification does not define what happens if a thread
  96   attempts to acquire a lock that it already holds. For applications
  97   that require locks to be safe when acquired recursively, see instead
  98   MAKE-RECURSIVE-LOCK and friends."
  99   (declare (ignore lock wait-p))
 100   t)
 101
 102 (defdfun release-lock (lock)
 103   "Release LOCK. It is an error to call this unless
 104   the lock has previously been acquired (and not released) by the same
 105   thread. If other threads are waiting for the lock, the
 106   ACQUIRE-LOCK call in one of them will now be able to continue.
 107
 108   This function has no interesting return value."
 109   (declare (ignore lock))
 110   (values))
 111
 112 (defdmacro with-lock-held ((place) &body body)
 113   "Evaluates BODY with the lock named by PLACE, the value of which
 114   is a lock created by MAKE-LOCK. Before the forms in BODY are
 115   evaluated, the lock is acquired as if by using ACQUIRE-LOCK. After the
 116   forms in BODY have been evaluated, or if a non-local control transfer
 117   is caused (e.g. by THROW or SIGNAL), the lock is released as if by
 118   RELEASE-LOCK.
 119
 120   Note that if the debugger is entered, it is unspecified whether the
 121   lock is released at debugger entry or at debugger exit when execution
 122   is restarted."
 123   `(when (acquire-lock ,place t)
 124      (unwind-protect
 125           (locally ,@body)
 126        (release-lock ,place))))
 127
 128 (defdfun make-recursive-lock (&optional name)
 129   "Create and return a recursive lock whose name is NAME. A recursive
 130   lock differs from an ordinary lock in that a thread that already
 131   holds the recursive lock can acquire it again without blocking. The
 132   thread must then release the lock twice before it becomes available
 133   for another thread."
 134   (declare (ignore name))
 135   (list nil))
 136
 137 (defdfun acquire-recursive-lock (lock)
 138   "As for ACQUIRE-LOCK, but for recursive locks."
 139   (declare (ignore lock))
 140   t)
 141
 142 (defdfun release-recursive-lock (lock)
 143   "Release the recursive LOCK. The lock will only
 144   become free after as many Release operations as there have been
 145   Acquire operations. See RELEASE-LOCK for other information."
 146   (declare (ignore lock))
 147   (values))
 148
 149 (defdmacro with-recursive-lock-held ((place &key timeout) &body body)
 150   "Evaluates BODY with the recursive lock named by PLACE, which is a
 151 reference to a recursive lock created by MAKE-RECURSIVE-LOCK. See
 152 WITH-LOCK-HELD etc etc"
 153   (declare (ignore timeout))
 154   `(when (acquire-recursive-lock ,place)
 155      (unwind-protect
 156           (locally ,@body)
 157        (release-recursive-lock ,place))))
 158
 159 ;;; Resource contention: condition variables
 160
 161 ;;; A condition variable provides a mechanism for threads to put
 162 ;;; themselves to sleep while waiting for the state of something to
 163 ;;; change, then to be subsequently woken by another thread which has
 164 ;;; changed the state.
 165 ;;;
 166 ;;; A condition variable must be used in conjunction with a lock to
 167 ;;; protect access to the state of the object of interest. The
 168 ;;; procedure is as follows:
 169 ;;;
 170 ;;; Suppose two threads A and B, and some kind of notional event
 171 ;;; channel C. A is consuming events in C, and B is producing them.
 172 ;;; CV is a condition-variable
 173 ;;;
 174 ;;; 1) A acquires the lock that safeguards access to C
 175 ;;; 2) A threads and removes all events that are available in C
 176 ;;; 3) When C is empty, A calls CONDITION-WAIT, which atomically
 177 ;;;    releases the lock and puts A to sleep on CV
 178 ;;; 4) Wait to be notified; CONDITION-WAIT will acquire the lock again
 179 ;;;    before returning
 180 ;;; 5) Loop back to step 2, for as long as threading should continue
 181 ;;;
 182 ;;; When B generates an event E, it
 183 ;;; 1) acquires the lock guarding C
 184 ;;; 2) adds E to the channel
 185 ;;; 3) calls CONDITION-NOTIFY on CV to wake any sleeping thread
 186 ;;; 4) releases the lock
 187 ;;;
 188 ;;; To avoid the "lost wakeup" problem, the implementation must
 189 ;;; guarantee that CONDITION-WAIT in thread A atomically releases the
 190 ;;; lock and sleeps. If this is not guaranteed there is the
 191 ;;; possibility that thread B can add an event and call
 192 ;;; CONDITION-NOTIFY between the lock release and the sleep - in this
 193 ;;; case the notify call would not see A, which would be left sleeping
 194 ;;; despite there being an event available.
 195
 196 (defdfun thread-yield ()
 197   "Allows other threads to run. It may be necessary or desirable to
 198   call this periodically in some implementations; others may schedule
 199   threads automatically. On systems that do not support
 200   multi-threading, this does nothing."
 201   (values))
 202
 203 (defdfun make-condition-variable ()
 204   "Returns a new condition-variable object for use
 205   with CONDITION-WAIT and CONDITION-NOTIFY."
 206   nil)
 207
 208 (defdfun condition-wait (condition-variable lock)
 209   "Atomically release LOCK and enqueue the calling
 210   thread waiting for CONDITION-VARIABLE. The thread will resume when
 211   another thread has notified it using CONDITION-NOTIFY; it may also
 212   resume if interrupted by some external event or in other
 213   implementation-dependent circumstances: the caller must always test
 214   on waking that there is threading to be done, instead of assuming
 215   that it can go ahead.
 216
 217   However and for whatever reason the thread is resumed, the system
 218   always reacquires LOCK before returning to the caller. It is an
 219   error to call this unless from the thread that holds LOCK.
 220
 221   In an implementation that does not support multiple threads, this
 222   function signals an error."
 223   (declare (ignore condition-variable lock))
 224   (error (make-threading-support-error)))
 225
 226 (defdfun condition-notify (condition-variable)
 227   "Notify at least one of the threads waiting for
 228   CONDITION-VARIABLE. It is implementation-dependent whether one or
 229   more than one (and possibly all) threads are woken, but if the
 230   implementation is capable of waking only a single thread (not all
 231   are) this is probably preferable for efficiency reasons. The order
 232   of wakeup is unspecified and does not necessarily relate to the
 233   order that the threads went to sleep in.
 234
 235   CONDITION-NOTIFY has no useful return value. In an implementation
 236   that does not support multiple threads, it has no effect."
 237   (declare (ignore condition-variable))
 238   (values))
 239
 240 ;;; Introspection/debugging
 241
 242 ;;; The following functions may be provided for debugging purposes,
 243 ;;; but are not advised to be called from normal user code.
 244
 245 (defdfun all-threads ()
 246   "Returns a sequence of all of the threads. This may not
 247   be freshly-allocated, so the caller should not modify it."
 248   (error (make-threading-support-error)))
 249
 250 (defdfun interrupt-thread (thread function)
 251   "Interrupt THREAD and cause it to evaluate FUNCTION
 252   before continuing with the interrupted path of execution. This may
 253   not be a good idea if THREAD is holding locks or doing anything
 254   important. On systems that do not support multiple threads, this
 255   function signals an error."
 256   (declare (ignore thread function))
 257   (error (make-threading-support-error)))
 258
 259 (defdfun destroy-thread (thread)
 260   "Terminates the thread THREAD, which is an object
 261   as returned by MAKE-THREAD. This should be used with caution: it is
 262   implementation-defined whether the thread runs cleanup forms or
 263   releases its locks first.
 264
 265   Destroying the calling thread is an error."
 266   (declare (ignore thread))
 267   (error (make-threading-support-error)))
 268
 269 (defdfun thread-alive-p (thread)
 270   "Returns true if THREAD is alive, that is, if
 271   DESTROY-THREAD has not been called on it."
 272   (declare (ignore thread))
 273   (error (make-threading-support-error)))