Sternly advise against non-debugging use of THREAD-MUTEX-OWNER.

diff --git a/src/runtime/thread.scm b/src/runtime/thread.scm
index c9c766ffd78339ff9f18f29e5fcd096aab8cb65e..902bbcf1d88515c28c2bce40c3d8fed58236fbdd 100644 (file)
--- a/src/runtime/thread.scm
+++ b/src/runtime/thread.scm
@@ -1048,6 +1048,12 @@ USA.
          (error "Don't own mutex:" mutex)
          (error "Don't own mutex:" mutex caller))))
 
+;;; Never use THREAD-MUTEX-OWNER except as a debugging feature.  If you
+;;; are tempted to make locking decisions on the basis of who owns a
+;;; mutex, fix your design so you're no longer tempted.  Mutexes are
+;;; non-recursive.  Use ASSERT-THREAD-MUTEX-OWNED to assert that you
+;;; own a mutex so you're less tempted to call THREAD-MUTEX-OWNER ever.
+
 (define (thread-mutex-owner mutex)
   (guarantee-thread-mutex mutex 'THREAD-MUTEX-OWNER)
   (thread-mutex/owner mutex))