Bugzilla bug 84035: improved comments.

Tag: NSPRPUB_PRE_4_2_CLIENT_BRANCH

1 files changed, 26 insertions, 8 deletions

diff --git a/pr/include/md/_pth.h b/pr/include/md/_pth.h
index 98331793..be65ab74 100644
--- a/pr/include/md/_pth.h
+++ b/pr/include/md/_pth.h
@@ -97,15 +97,33 @@
 #endif
 
 /* The pthreads standard does not specify an invalid value for the
- * pthread_t handle.  These macros define a way to set the handle
- * to or compare the handle with an invalid identifier.  These
- * macros are not portable and may be more of a problem as we adapt
- * to more pthreads implementations.  They are only used in the
- * PRMonitor functions.  Do not use them in new code.
+ * pthread_t handle.  (0 is usually an invalid pthread identifier
+ * but there are exceptions, for example, DG/UX.)  These macros
+ * define a way to set the handle to or compare the handle with an
+ * invalid identifier.  These macros are not portable and may be
+ * more of a problem as we adapt to more pthreads implementations.
+ * They are only used in the PRMonitor functions.  Do not use them
+ * in new code.
  *
- * Unfortunately some of our clients are depending on certain
- * properties of our current PRMonitor implementation, preventing
- * me from replacing it by a portable implementation.
+ * Unfortunately some of our clients depend on certain properties
+ * of our PRMonitor implementation, preventing us from replacing
+ * it by a portable implementation.
+ * - High-performance servers like the fact that PR_EnterMonitor
+ *   only calls PR_Lock and PR_ExitMonitor only calls PR_Unlock.
+ *   (A portable implementation would use a PRLock and a PRCondVar
+ *   to implement the recursive lock in a monitor and call both
+ *   PR_Lock and PR_Unlock in PR_EnterMonitor and PR_ExitMonitor.)
+ *   Unfortunately this forces us to read the monitor owner field
+ *   without holding a lock.
+ * - One way to make it safe to read the monitor owner field
+ *   without holding a lock is to make that field a PRThread*
+ *   (one should be able to read a pointer with a single machine
+ *   instruction).  However, PR_GetCurrentThread calls calloc if
+ *   it is called by a thread that was not created by NSPR.  The
+ *   malloc tracing tools in the Mozilla client use PRMonitor for
+ *   locking in their malloc, calloc, and free functions.  If
+ *   PR_EnterMonitor calls any of these functions, infinite
+ *   recursion ensues.
  */
 #if defined(_PR_DCETHREADS)
 #define _PT_PTHREAD_INVALIDATE_THR_HANDLE(t) \