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.

11 files changed, 99 insertions, 27 deletions

diff --git a/ChangeLog b/ChangeLog
index 98e4650..5e72a53 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,32 @@
+
+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.
+
 2000-04-03  Jeff Hobbs  <hobbs@scriptics.com>
 
 	* generic/tclCmdIL.c (InfoVarsCmd): checked for non-NULL procPtr
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
diff --git a/generic/tcl.decls b/generic/tcl.decls
index b9908f3..7c2837d 100644
--- a/generic/tcl.decls
+++ b/generic/tcl.decls
@@ -10,7 +10,7 @@
 # See the file "license.terms" for information on usage and redistribution
 # of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 # 
-# RCS: @(#) $Id: tcl.decls,v 1.31 2000/02/08 10:05:40 hobbs Exp $
+# RCS: @(#) $Id: tcl.decls,v 1.32 2000/04/04 20:28:40 kupries Exp $
 
 library tcl
 
@@ -1347,7 +1347,12 @@ declare 390 generic {
     int Tcl_ProcObjCmd(ClientData clientData, Tcl_Interp *interp, \
 	    int objc, Tcl_Obj *CONST objv[])
 }
-
+declare 391 generic {
+    void Tcl_ConditionFinalize (Tcl_Condition *condPtr)
+}
+declare 392 generic {
+    void Tcl_MutexFinalize (Tcl_Mutex *mutex)
+}
 
 ##############################################################################
 
diff --git a/generic/tcl.h b/generic/tcl.h
index dd13cd2..8ecd7d6 100644
--- a/generic/tcl.h
+++ b/generic/tcl.h
@@ -12,7 +12,7 @@
  * See the file "license.terms" for information on usage and redistribution
  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  *
- * RCS: @(#) $Id: tcl.h,v 1.63 2000/02/08 10:05:40 hobbs Exp $
+ * RCS: @(#) $Id: tcl.h,v 1.64 2000/04/04 20:28:41 kupries Exp $
  */
 
 #ifndef _TCL
@@ -163,8 +163,10 @@ extern "C" {
 #ifndef TCL_THREADS
 #define Tcl_MutexLock(mutexPtr)
 #define Tcl_MutexUnlock(mutexPtr)
+#define Tcl_MutexFinalize(mutexPtr)
 #define Tcl_ConditionNotify(condPtr)
 #define Tcl_ConditionWait(condPtr, mutexPtr, timePtr)
+#define Tcl_ConditionFinalize(condPtr)
 #endif /* TCL_THREADS */
 
 /* 
diff --git a/generic/tclDecls.h b/generic/tclDecls.h
index 05902e7..a670f78 100644
--- a/generic/tclDecls.h
+++ b/generic/tclDecls.h
@@ -8,7 +8,7 @@
  * See the file "license.terms" for information on usage and redistribution
  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  *
- * RCS: @(#) $Id: tclDecls.h,v 1.31 2000/02/08 10:05:41 hobbs Exp $
+ * RCS: @(#) $Id: tclDecls.h,v 1.32 2000/04/04 20:28:41 kupries Exp $
  */
 
 #ifndef _TCLDECLS
@@ -1218,6 +1218,11 @@ EXTERN int		Tcl_GetChannelNamesEx _ANSI_ARGS_((
 EXTERN int		Tcl_ProcObjCmd _ANSI_ARGS_((ClientData clientData, 
 				Tcl_Interp * interp, int objc, 
 				Tcl_Obj *CONST objv[]));
+/* 391 */
+EXTERN void		Tcl_FinalizeCondition _ANSI_ARGS_((
+				Tcl_Condition * condPtr));
+/* 392 */
+EXTERN void		Tcl_FinalizeMutex _ANSI_ARGS_((Tcl_Mutex * mutex));
 
 typedef struct TclStubHooks {
     struct TclPlatStubs *tclPlatStubs;
@@ -1676,6 +1681,8 @@ typedef struct TclStubs {
     int (*tcl_GetChannelNames) _ANSI_ARGS_((Tcl_Interp * interp)); /* 388 */
     int (*tcl_GetChannelNamesEx) _ANSI_ARGS_((Tcl_Interp * interp, char * pattern)); /* 389 */
     int (*tcl_ProcObjCmd) _ANSI_ARGS_((ClientData clientData, Tcl_Interp * interp, int objc, Tcl_Obj *CONST objv[])); /* 390 */
+    void (*tcl_FinalizeCondition) _ANSI_ARGS_((Tcl_Condition * condPtr)); /* 391 */
+    void (*tcl_FinalizeMutex) _ANSI_ARGS_((Tcl_Mutex * mutex)); /* 392 */
 } TclStubs;
 
 #ifdef __cplusplus
@@ -3285,6 +3292,14 @@ extern TclStubs *tclStubsPtr;
 #define Tcl_ProcObjCmd \
 	(tclStubsPtr->tcl_ProcObjCmd) /* 390 */
 #endif
+#ifndef Tcl_FinalizeCondition
+#define Tcl_FinalizeCondition \
+	(tclStubsPtr->tcl_FinalizeCondition) /* 391 */
+#endif
+#ifndef Tcl_FinalizeMutex
+#define Tcl_FinalizeMutex \
+	(tclStubsPtr->tcl_FinalizeMutex) /* 392 */
+#endif
 
 #endif /* defined(USE_TCL_STUBS) && !defined(USE_TCL_STUB_PROCS) */
 
diff --git a/generic/tclInt.h b/generic/tclInt.h
index 4b2176a..66a0cc1 100644
--- a/generic/tclInt.h
+++ b/generic/tclInt.h
@@ -11,7 +11,7 @@
  * See the file "license.terms" for information on usage and redistribution
  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  *
- * RCS: @(#) $Id: tclInt.h,v 1.40 2000/01/24 02:29:58 hobbs Exp $
+ * RCS: @(#) $Id: tclInt.h,v 1.41 2000/04/04 20:28:42 kupries Exp $
  */
 
 #ifndef _TCLINT
@@ -1623,8 +1623,6 @@ EXTERN int		TclFileRenameCmd _ANSI_ARGS_((Tcl_Interp *interp,
 			    int argc, char **argv)) ;
 EXTERN void		TclFinalizeAllocSubsystem _ANSI_ARGS_((void));
 EXTERN void		TclFinalizeCompExecEnv _ANSI_ARGS_((void));
-EXTERN void		TclFinalizeCondition _ANSI_ARGS_((
-			    Tcl_Condition *condPtr));
 EXTERN void		TclFinalizeCompilation _ANSI_ARGS_((void));
 EXTERN void		TclFinalizeEncodingSubsystem _ANSI_ARGS_((void));
 EXTERN void		TclFinalizeEnvironment _ANSI_ARGS_((void));
@@ -1632,7 +1630,6 @@ EXTERN void		TclFinalizeExecution _ANSI_ARGS_((void));
 EXTERN void		TclFinalizeIOSubsystem _ANSI_ARGS_((void));
 EXTERN void		TclFinalizeLoad _ANSI_ARGS_((void));
 EXTERN void		TclFinalizeMemorySubsystem _ANSI_ARGS_((void));
-EXTERN void		TclFinalizeMutex _ANSI_ARGS_((Tcl_Mutex *mutex));
 EXTERN void		TclFinalizeNotifier _ANSI_ARGS_((void));
 EXTERN void		TclFinalizeSynchronization _ANSI_ARGS_((void));
 EXTERN void		TclFinalizeThreadData _ANSI_ARGS_((void));
diff --git a/generic/tclNotify.c b/generic/tclNotify.c
index 2ce8f72..8c93cef 100644
--- a/generic/tclNotify.c
+++ b/generic/tclNotify.c
@@ -13,7 +13,7 @@
  * See the file "license.terms" for information on usage and redistribution
  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  *
- * RCS: @(#) $Id: tclNotify.c,v 1.6 1999/07/02 21:50:04 redman Exp $
+ * RCS: @(#) $Id: tclNotify.c,v 1.7 2000/04/04 20:28:42 kupries Exp $
  */
 
 #include "tclInt.h"
@@ -150,7 +150,7 @@ TclFinalizeNotifier()
     Tcl_MutexLock(&listLock);
 
     Tcl_FinalizeNotifier(tsdPtr->clientData);
-    TclFinalizeMutex(&(tsdPtr->queueMutex));
+    Tcl_MutexFinalize(&(tsdPtr->queueMutex));
     for (prevPtrPtr = &firstNotifierPtr; *prevPtrPtr != NULL;
 	 prevPtrPtr = &((*prevPtrPtr)->nextPtr)) {
 	if (*prevPtrPtr == tsdPtr) {
diff --git a/generic/tclStubInit.c b/generic/tclStubInit.c
index c2349d1..0c0fb19 100644
--- a/generic/tclStubInit.c
+++ b/generic/tclStubInit.c
@@ -8,7 +8,7 @@
  * See the file "license.terms" for information on usage and redistribution
  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  *
- * RCS: @(#) $Id: tclStubInit.c,v 1.32 2000/03/31 08:52:06 hobbs Exp $
+ * RCS: @(#) $Id: tclStubInit.c,v 1.33 2000/04/04 20:28:43 kupries Exp $
  */
 
 #include "tclInt.h"
@@ -788,6 +788,8 @@ TclStubs tclStubs = {
     Tcl_GetChannelNames, /* 388 */
     Tcl_GetChannelNamesEx, /* 389 */
     Tcl_ProcObjCmd, /* 390 */
+    Tcl_FinalizeCondition, /* 391 */
+    Tcl_FinalizeMutex, /* 392 */
 };
 
 /* !END!: Do not edit above this line. */
diff --git a/generic/tclThread.c b/generic/tclThread.c
index a192f43..69142ae 100644
--- a/generic/tclThread.c
+++ b/generic/tclThread.c
@@ -9,7 +9,7 @@
  * See the file "license.terms" for information on usage and redistribution
  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  *
- * RCS: @(#) $Id: tclThread.c,v 1.3 1999/08/10 17:35:19 redman Exp $
+ * RCS: @(#) $Id: tclThread.c,v 1.4 2000/04/04 20:28:43 kupries Exp $
  */
 
 #include "tclInt.h"
@@ -271,7 +271,7 @@ TclRememberMutex(mutexPtr)
 /*
  *----------------------------------------------------------------------
  *
- * TclFinalizeMutex
+ * Tcl_MutexFinalize
  *
  *      Finalize a single mutex and remove it from the
  *	list of remembered objects.
@@ -286,7 +286,7 @@ TclRememberMutex(mutexPtr)
  */
 
 void
-TclFinalizeMutex(mutexPtr)
+Tcl_MutexFinalize(mutexPtr)
     Tcl_Mutex *mutexPtr;
 {
 #ifdef TCL_THREADS
@@ -344,7 +344,7 @@ TclRememberCondition(condPtr)
 /*
  *----------------------------------------------------------------------
  *
- * TclFinalizeCondition
+ * Tcl_ConditionFinalize
  *
  *      Finalize a single condition variable and remove it from the
  *	list of remembered objects.
@@ -359,7 +359,7 @@ TclRememberCondition(condPtr)
  */
 
 void
-TclFinalizeCondition(condPtr)
+Tcl_ConditionFinalize(condPtr)
     Tcl_Condition *condPtr;
 {
 #ifdef TCL_THREADS
@@ -411,7 +411,7 @@ TclFinalizeThreadData()
 /*
  *----------------------------------------------------------------------
  *
- * TclFinalizeSyncronization --
+ * TclFinalizeSynchronization --
  *
  *      This procedure cleans up all synchronization objects:
  *      mutexes, condition variables, and thread-local storage.
diff --git a/generic/tclThreadTest.c b/generic/tclThreadTest.c
index 9aa43d5..d924d4f 100644
--- a/generic/tclThreadTest.c
+++ b/generic/tclThreadTest.c
@@ -11,7 +11,7 @@
  * See the file "license.terms" for information on usage and redistribution
  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  *
- * RCS: @(#) $Id: tclThreadTest.c,v 1.6 2000/01/12 11:12:53 hobbs Exp $
+ * RCS: @(#) $Id: tclThreadTest.c,v 1.7 2000/04/04 20:28:43 kupries Exp $
  */
 
 #include "tclInt.h"
@@ -372,7 +372,7 @@ TclCreateThread(interp, script)
 
     Tcl_ConditionWait(&ctrl.condWait, &threadMutex, NULL);
     Tcl_MutexUnlock(&threadMutex);
-    TclFinalizeCondition(&ctrl.condWait);
+    Tcl_ConditionFinalize(&ctrl.condWait);
     Tcl_SetObjResult(interp, Tcl_NewLongObj((long)id));
     return TCL_OK;
 }
@@ -764,7 +764,7 @@ TclThreadSend(interp, id, script, wait)
 	}
     }
     Tcl_SetResult(interp, resultPtr->result, TCL_DYNAMIC);
-    TclFinalizeCondition(&resultPtr->done);
+    Tcl_ConditionFinalize(&resultPtr->done);
     code = resultPtr->code;
 
     ckfree((char *) resultPtr);
diff --git a/unix/tclUnixNotfy.c b/unix/tclUnixNotfy.c
index f2c670b..5098f93 100644
--- a/unix/tclUnixNotfy.c
+++ b/unix/tclUnixNotfy.c
@@ -11,7 +11,7 @@
  * See the file "license.terms" for information on usage and redistribution
  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  *
- * RCS: @(#) $Id: tclUnixNotfy.c,v 1.7 2000/01/21 02:26:25 hobbs Exp $
+ * RCS: @(#) $Id: tclUnixNotfy.c,v 1.8 2000/04/04 20:28:43 kupries Exp $
  */
 
 #include "tclInt.h"
@@ -272,7 +272,7 @@ Tcl_FinalizeNotifier(clientData)
      * Clean up any synchronization objects in the thread local storage.
      */
 
-    TclFinalizeCondition(&(tsdPtr->waitCV));
+    Tcl_ConditionFinalize(&(tsdPtr->waitCV));
 
     Tcl_MutexUnlock(&notifierMutex);
 #endif