+(defun grab-mutex (mutex &key (new-owner *current-thread*)
+ (waitp t) (timeout nil))
+ #!+sb-doc
+ "Acquire MUTEX for NEW-OWNER, which must be a thread or NIL. If
+NEW-OWNER is NIL, it defaults to the current thread. If WAITP is
+non-NIL and the mutex is in use, sleep until it is available.
+
+If TIMEOUT is given, it specifies a relative timeout, in seconds, on
+how long GRAB-MUTEX should try to acquire the lock in the contested
+case.
+
+If GRAB-MUTEX returns T, the lock acquisition was successful. In case
+of WAITP being NIL, or an expired TIMEOUT, GRAB-MUTEX may also return
+NIL which denotes that GRAB-MUTEX did -not- acquire the lock.
+
+Notes:
+
+ - Using the NEW-OWNER parameter to assign a MUTEX to another thread
+ than the current one is not recommended, and liable to be
+ deprecated.
+
+ - GRAB-MUTEX is not interrupt safe. The correct way to call it is:
+
+ (WITHOUT-INTERRUPTS
+ ...
+ (ALLOW-WITH-INTERRUPTS (GRAB-MUTEX ...))
+ ...)
+
+ WITHOUT-INTERRUPTS is necessary to avoid an interrupt unwinding
+ the call while the mutex is in an inconsistent state while
+ ALLOW-WITH-INTERRUPTS allows the call to be interrupted from
+ sleep.
+
+ - The TIMEOUT parameter is currently only supported on non-SB-LUTEX
+ platforms like Linux or BSD.
+
+ - (GRAB-MUTEX <mutex> :timeout 0.0) differs from
+ (GRAB-MUTEX <mutex> :waitp nil) in that the former may signal a
+ DEADLINE-TIMEOUT if the global deadline was due already on
+ entering GRAB-MUTEX.
+
+ The exact interplay of GRAB-MUTEX and deadlines are reserved to
+ change in future versions.
+
+ - It is recommended that you use WITH-MUTEX instead of calling
+ GRAB-MUTEX directly.
+"
+ (get-mutex mutex new-owner waitp timeout))
+