2000-04-03 Andreas Kupries <a.kupries@westend.com>

	* Overall change: Definition of public API's for the finalization
	of conditions and mutexes. [Bug: 4199].

	* generic/tclInt.h: Removed definitions of TclFinalizeMutex and
	TclFinalizeCondition.

	* generic/tcl.decls: Added declarations of Tcl_MutexFinalize and
	Tcl_ConditionFinalize.

	* generic/tclThread.c: Renamed TclFinalizeMutex to
	Tcl_MutexFinalize. Renamed TclFinalizeCondition to
	Tcl_ConditionFinalize.

	* generic/tclNotify.c: Changed usage of TclFinalizeMutex to
	Tcl_MutexFinalize.

	* unix/tclUnixNotfy.c:
	* generic/tclThreadTest.c: Changed usages of TclFinalizeCondition to
	Tcl_ConditionFinalize.

	* generic/tcl.h: Added empty macros for Tcl_MutexFinalize and
	Tcl_ConditionFinalize, to be used when the core is compiled
	without threads.

	* doc/Thread.3:	Added description the new API's.

1 files changed, 27 insertions, 5 deletions

diff --git a/doc/Thread.3 b/doc/Thread.3
index 9e473b8..cd50dbc 100644
--- a/doc/Thread.3
+++ b/doc/Thread.3
@@ -5,13 +5,15 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Thread.3,v 1.7 1999/08/21 19:40:48 hobbs Exp $
+'\" RCS: @(#) $Id: Thread.3,v 1.8 2000/04/04 20:28:40 kupries Exp $
 '\" 
 .so man.macros
 .TH Threads 3 "8.1" Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock \- Tcl thread support.
+Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize,
+Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize
+\- Tcl thread support.
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -22,6 +24,9 @@ void
 void
 \fBTcl_ConditionWait\fR(\fIcondPtr, mutexPtr, timePtr\fR)
 .sp
+void
+\fBTcl_ConditionFinalize\fR(\fIcondPtr\fR)
+.sp
 Void *
 \fBTcl_GetThreadData\fR(\fIkeyPtr, size\fR)
 .sp
@@ -30,6 +35,9 @@ void
 .sp
 void
 \fBTcl_MutexUnlock\fR(\fImutexPtr\fR)
+.sp
+void
+\fBTcl_MutexFinalize\fR(\fImutexPtr\fR)
 .SH ARGUMENTS
 .AS Tcl_ThreadDataKey *keyPtr
 .AP Tcl_Condition *condPtr in
@@ -89,10 +97,11 @@ 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.
 .VS
+A mutex can be destroyed after its use by calling \fBTcl_MutexFinalize\fR.
 The result of locking a mutex twice from the same thread is undefined.
 On some platforms it will result in a deadlock.
 .VE
-\fBTcl_MutexLock\fR and \fBTcl_MutexUnlock\fR
+The \fBTcl_MutexLock\fR, \fBTcl_MutexUnlock\fR and \fBTcl_MutexFinalize\fR
 procedures are defined as empty macros if not compiling with threads enabled.
 .PP
 A condition variable is used as a signaling mechanism:
@@ -111,6 +120,15 @@ The caller of \fBTcl_ConditionWait\fR should be prepared for spurious
 notifications by calling \fBTcl_ConditionWait\fR within a while loop
 that tests some invariant.
 .PP
+.VS
+A condition variable can be destroyed after its use by calling
+\fBTcl_ConditionFinalize\fR.
+.PP
+The \fBTcl_ConditionNotify\fR, \fBTcl_ConditionWait\fR and
+\fBTcl_ConditionFinalize\fR procedures are defined as empty macros if
+not compiling with threads enabled.
+.VE
+.PP
 The \fBTcl_GetThreadData\fR call returns a pointer to a block of
 thread-private data.  Its argument is a key that is shared by all threads
 and a size for the block of storage.  The storage is automatically 
@@ -122,8 +140,12 @@ All of these synchronization objects are self initializing.
 They are implemented as opaque pointers that should be NULL
 upon first use.
 The mutexes and condition variables are
-cleaned up by process exit handlers.  Thread local storage is
-reclaimed during \fBTcl_FinalizeThread\fR.
+.VS
+either cleaned up by process exit handlers (if living that long) or
+explicitly by calls to \fBTcl_MutexFinalize\fR or
+\fBTcl_ConditionFinalize\fR.
+.VE
+Thread local storage is reclaimed during \fBTcl_FinalizeThread\fR.
 .SH "CREATING THREADS"
 The API to create threads is not finalized at this time.
 There are private facilities to create threads that contain a new