2000-05-02 Andreas Kupries <a.kupries@westend.com>

	* Overall changes:
	  (1) Implementation of joinable threads for all platforms.
	  (2) Additional API's for channels. Required to allow the
	  thread extension to move channels between threads.

	* generic/tcl.decls (lines 1360f): Added Tcl_JoinThread,
	  Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel,
	  Tcl_SpliceChannel, Tcl_IsChannelExisting and
	  Tcl_ClearChannelHandlers (slots 394 to 400).

	* generic/tclIO.c: Implemented Tcl_IsChannelRegistered,
 	  Tcl_IsChannelShared, Tcl_CutChannel, Tcl_SpliceChannel,
 	  Tcl_IsChannelExisting and Tcl_ClearChannelHandlers.
	  Tcl_CutChannel uses code from CloseChannel. Replaced this code
 	  by a call to Tcl_CutChannel.  Replaced several code fragments
 	  adding channels to the channel list with calls to
 	  Tcl_SpliceChannel. Removed now unused variables from
 	  CloseChannel and Tcl_UnstackChannel.  Tcl_ClearChannelHandlers
 	  uses code from Tcl_Close. Replaced this code by a call to
 	  Tcl_ClearChannelHandlers. Removed now unused variables from
 	  Tcl_Close. Added the subcommands 'cut', 'forgetch', 'splice' and
 	  'isshared' to the test code
	  (TclTestChannelCmd).

	* unix/tclUnixThread.c: Implemented Tcl_JoinThread using the
	  pthread-functionality.

	* win/tclWinThrd.c: Fixed several small typos in comments.
	  Implemented Tcl_JoinThread using a platform independent
	  emulation layer (see generic/tclThreadJoin.c below). Added
	  'joinLock' to serialize Tcl_CreateThread and TclpExitThread to
	  prevent a race for joinable threads.

	* mac/tclMacThrd.c: Implemented Tcl_JoinThread using a platform
	  independent emulation layer (see generic/tclThreadJoin.c
	  below). Due to the cooperative nature of threading on this
	  platform the race mentioned above is not present.

	* generic/tclThreadJoin.c: New file. Contains a platform
	  independent emulation layer helping in the implementation of
	  joinable threads for the win and mac platforms.

	* generic/tclInt.h: Added declarations for TclJoinThread,
	  TclRememberJoinableThread and TclSignalExitThread. These
	  procedures define the API of the emulation layer for joinable
	  threads (see generic/tclThreadJoin.c above).

	* win/Makefile.in:
	* win/makefile.vc: Added generic/tclTheadJoin.o to the rules.

	* mac/: I don't know to which file generic/tclTheadJoin.o has to
	  be added to so that it compiles. Sorry.

	* unix/tclUnixChan.c: #ifdef'd the thread-local list of file
 	  channels as it prevents us from transfering channels. To restore
 	  this we may need an extended interface to drivers in the
 	  future. Target: 9.0. Found while testing the new transfer of
 	  channels. The information in this list for a channel was left
 	  behind and then crashed the system during finalization.

	* generic/tclThreadTest.c: Added -joinable flag to 'testthread
	  create'. Added subcommand 'testthread join'.

	* doc/CrtChannel.3: Added documentation for Tcl_IsChannelRegistered,
 	  Tcl_IsChannelShared, Tcl_CutChannel, Tcl_SpliceChannel,
	  Tcl_IsChannelExisting and Tcl_ClearChannelHandlers.

	* doc/Thread.3: Added documentation for Tcl_JoinThread.

	* tests/thread.test: Added tests for joining of threads.

1 files changed, 23 insertions, 1 deletions

diff --git a/doc/Thread.3 b/doc/Thread.3
index 0afcb80..0be6879 100644
--- a/doc/Thread.3
+++ b/doc/Thread.3
@@ -5,7 +5,7 @@
 '\" 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.11 2000/04/25 23:03:53 hobbs Exp $
+'\" RCS: @(#) $Id: Thread.3,v 1.12 2000/05/02 22:02:33 kupries Exp $
 '\" 
 .so man.macros
 .TH Threads 3 "8.1" Tcl "Tcl Library Procedures"
@@ -39,6 +39,9 @@ void
 .sp
 int
 \fBTcl_CreateThread\fR(\fIidPtr, threadProc, clientData, stackSize, flags\fR)
+.sp
+int
+\fBTcl_JoinThread\fR(\fIid, result\fR)
 .SH ARGUMENTS
 .AS Tcl_ThreadDataKey *keyPtr
 .AP Tcl_Condition *condPtr in
@@ -59,6 +62,8 @@ calls \fBTcl_GetThreadData\fR.
 .AP Tcl_ThreadId *idPtr out
 The refered storage will contain the id of the newly created thread as
 returned by the operating system.
+.AP Tcl_ThreadId id in
+Id of the thread waited upon.
 .AP Tcl_ThreadCreateProc threadProc in
 This procedure will act as the \fBmain()\fR of the newly created
 thread. The specified \fIclientData\fR will be its sole argument.
@@ -69,6 +74,9 @@ The size of the stack given to the new thread.
 .AP int flags in
 Bitmask containing flags allowing the caller to modify behaviour of
 the new thread.
+.AP int *result out
+The refered storage is used to place the exit code of the thread
+waited upon into it.
 .BE
 .SH INTRODUCTION
 Beginning with the 8.1 release, the Tcl core is thread safe, which
@@ -109,6 +117,20 @@ for terminating threads and invoking optional per-thread exit
 handlers.  See the \fBTcl_Exit\fR page for more information on these
 procedures.
 .PP
+.VS
+The \fBTcl_JoinThread\fR function is provided to allow threads to wait
+upon the exit of another thread, which must have been marked as
+joinable through usage of the \fBTCL_THREAD_JOINABLE\fR-flag during
+its creation via \fBTcl_CreateThread\fR.
+.PP
+Trying to wait for the exit of a non-joinable thread or a thread which
+is already waited upon will result in an error. Waiting for a joinable
+thread which already exited is possible, the system will retain the
+necessary information until after the call to \fBTcl_JoinThread\fR.
+This means that not calling \fBTcl_JoinThread\fR for a joinable thread
+will cause a memory leak.
+.VE
+.PP
 Tcl provides \fBTcl_ThreadQueueEvent\fR and \fBTcl_ThreadAlert\fR
 for handling event queueing in multithreaded applications.  See
 the \fBNotifier\fR manual page for more information on these procedures.