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.

2 files changed, 71 insertions, 5 deletions

diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3
index f95f653..1943a7d 100644
--- a/doc/CrtChannel.3
+++ b/doc/CrtChannel.3
@@ -4,13 +4,13 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: CrtChannel.3,v 1.5 2000/04/14 23:01:49 hobbs Exp $
+'\" RCS: @(#) $Id: CrtChannel.3,v 1.6 2000/05/02 22:02:33 kupries Exp $
 .so man.macros
 .TH Tcl_CreateChannel 3 8.0 Tcl "Tcl Library Procedures"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption \- procedures for creating and manipulating channels
+Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers \- procedures for creating and manipulating channels
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -42,6 +42,24 @@ int
 .sp
 int
 \fBTcl_BadChannelOption\fR(\fIinterp, optionName, optionList\fR)
+.sp
+int
+\fBTcl_IsChannelShared\fR(\fIchannel\fR)
+.sp
+int
+\fBTcl_IsChannelRegistered\fR(\fIinterp, channel\fR)
+.sp
+int
+\fBTcl_IsChannelExisting\fR(\fIchannelName\fR)
+.sp
+void
+\fBTcl_CutChannel\fR(\fIchannel\fR)
+.sp
+void
+\fBTcl_SpliceChannel\fR(\fIchannel\fR)
+.sp
+void
+\fBTcl_ClearChannelHandlers\fR(\fIchannel\fR)
 .VE
 .sp
 .SH ARGUMENTS
@@ -165,7 +183,7 @@ for each driver to determine what type of handle is returned.
 and \fBTCL_WRITABLE\fR, indicating whether the channel is open for input
 and output.
 .PP
- \fBTcl_GetChannelBufferSize\fR returns the size, in bytes, of buffers
+\fBTcl_GetChannelBufferSize\fR returns the size, in bytes, of buffers
 allocated to store input or output in \fIchan\fR. If the value was not set
 by a previous call to \fBTcl_SetChannelBufferSize\fR, described below, then
 the default value of 4096 is returned.
@@ -189,7 +207,33 @@ channel.  See \fBWATCHPROC\fR below for more details.
 \fBTcl_BadChannelOption\fR is called from driver specific set or get option
 procs to generate a complete error message.
 .VE
-
+.PP
+.VS
+\fBTcl_IsChannelShared\fR checks the refcount of the specified
+\fIchannel\fR and returns whether the \fIchannel\fR was shared among
+multiple interpreters (result == 1) or not (result == 0).
+.PP
+\fBTcl_IsChannelRegistered\fR checks wether the specified \fIchannel\fR is
+registered in the given \fIinterp\fRreter (result == 1) or not
+(result == 0).
+.PP
+\fBTcl_IsChannelExisting\fR checks wether a channel with the specified
+name is registered in the (thread)-global list of all channels (result
+== 1) or not (result == 0).
+.PP
+\fBTcl_CutChannel\fR removes the specified \fIchannel\fR from the
+(thread)global list of all channels (of the current thread).
+Application to a channel still registered in some interpreter
+is not allowed.
+.PP
+\fBTcl_SpliceChannel\fR adds the specified \fIchannel\fR to the
+(thread)global list of all channels (of the current thread).
+Application to a channel registered in some interpreter is not allowed.
+.PP
+\fBTcl_ClearChannelHandlers\fR removes all channelhandlers and event
+scripts associated with the specified \fIchannels\fR, thus shutting
+down all event processing for this channel.
+.VE
 .SH TCL_CHANNELTYPE
 .PP
 A channel driver provides a \fBTcl_ChannelType\fR structure that contains
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.