First draft of the necessary doc changes.

1 files changed, 13 insertions, 6 deletions

diff --git a/doc/Thread.3 b/doc/Thread.3
index ac5f2ba..ce449ba 100644
--- a/doc/Thread.3
+++ b/doc/Thread.3
@@ -9,7 +9,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize, Tcl_CreateThread, Tcl_JoinThread \- Tcl thread support
+Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize, Tcl_MutexUnlockAndFinalize, Tcl_CreateThread, Tcl_JoinThread \- Tcl thread support
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -35,6 +35,9 @@ void
 void
 \fBTcl_MutexFinalize\fR(\fImutexPtr\fR)
 .sp
+void
+\fBTcl_MutexUnlockAndFinalize\fR(\fImutexPtr\fR)
+.sp
 int
 \fBTcl_CreateThread\fR(\fIidPtr, proc, clientData, stackSize, flags\fR)
 .sp
@@ -138,11 +141,15 @@ A mutex is a lock that is used to serialize all threads through a piece
 of code by calling \fBTcl_MutexLock\fR and \fBTcl_MutexUnlock\fR.
 If one thread holds a mutex, any other thread calling \fBTcl_MutexLock\fR will
 block until \fBTcl_MutexUnlock\fR is called.
-A mutex can be destroyed after its use by calling \fBTcl_MutexFinalize\fR.
+A mutex can be destroyed after its use by calling \fBTcl_MutexFinalize\fR or
+\fBTcl_MutexUnlockAndFinalize\fR.  It is illegal to destroy a locked mutex
+with \fBTcl_MutexFinalize\fR; however, it is legal to destroy a locked mutex
+with \fBTcl_MutexUnlockAndFinalize\fR.
 The result of locking a mutex twice from the same thread is undefined.
 On some platforms it will result in a deadlock.
-The \fBTcl_MutexLock\fR, \fBTcl_MutexUnlock\fR and \fBTcl_MutexFinalize\fR
-procedures are defined as empty macros if not compiling with threads enabled.
+The \fBTcl_MutexLock\fR, \fBTcl_MutexUnlock\fR, \fBTcl_MutexFinalize\fR, and
+\fBTcl_MutexUnlockAndFinalize\fR procedures are defined as empty macros if
+not compiling with threads enabled.
 For declaration of mutexes the \fBTCL_DECLARE_MUTEX\fR macro should be used.
 This macro assures correct mutex handling even when the core is compiled
 without threads enabled.
@@ -176,8 +183,8 @@ They are implemented as opaque pointers that should be NULL
 upon first use.
 The mutexes and condition variables are
 either cleaned up by process exit handlers (if living that long) or
-explicitly by calls to \fBTcl_MutexFinalize\fR or
-\fBTcl_ConditionFinalize\fR.
+explicitly by calls to \fBTcl_MutexFinalize\fR (or
+\fBTcl_MutexUnlockAndFinalize\fR) and \fBTcl_ConditionFinalize\fR.
 Thread local storage is reclaimed during \fBTcl_FinalizeThread\fR.
 .SH "SCRIPT-LEVEL ACCESS TO THREADS"
 .PP