merged tcl 8.1 branch back into the main trunk

1 files changed, 37 insertions, 9 deletions

diff --git a/doc/Exit.3 b/doc/Exit.3
index b3f2ca6..c533efe 100644
--- a/doc/Exit.3
+++ b/doc/Exit.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: Exit.3,v 1.2 1998/09/14 18:39:48 stanton Exp $
+'\" RCS: @(#) $Id: Exit.3,v 1.3 1999/04/16 00:46:31 stanton Exp $
 '\" 
 .so man.macros
-.TH Tcl_Exit 3 7.7 Tcl "Tcl Library Procedures"
+.TH Tcl_Exit 3 8.1 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler \- end the application (and invoke exit handlers)
+Tcl_Exit, Tcl_Finalize, Tcl_FinalizeThread, Tcl_CreateExitHandler, Tcl_DeleteExitHandler, Tcl_CreateThreadExitHandler, Tcl_DeleteThreadExitHandler \- end the application or thread (and invoke exit handlers)
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -22,10 +22,19 @@ Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler \- end the
 \fBTcl_CreateExitHandler\fR(\fIproc, clientData\fR)
 .sp
 \fBTcl_DeleteExitHandler\fR(\fIproc, clientData\fR)
+.sp
+\fBTcl_ExitThread\fR(\fIstatus\fR)
+.sp
+\fBTcl_FinalizeThread\fR()
+.sp
+\fBTcl_CreateThreadExitHandler\fR(\fIproc, clientData\fR)
+.sp
+\fBTcl_DeleteThreadExitHandler\fR(\fIproc, clientData\fR)
 .SH ARGUMENTS
 .AS Tcl_ExitProc clientData
 .AP int status  in
-Provides information about why application exited.  Exact meaning may
+Provides information about why the application or thread exited.
+Exact meaning may
 be platform-specific.  0 usually means a normal exit, any nonzero value
 usually means that an error occurred.
 .AP Tcl_ExitProc *proc in
@@ -51,7 +60,6 @@ otherwise causes the application to terminate without calling
 \fBTcl_Exit\fR internally invokes the \fBexit\fR system call, thus it never
 returns control to its caller.
 .PP
-.VS
 \fBTcl_Finalize\fR is similar to \fBTcl_Exit\fR except that it does not
 exit from the current process.
 It is useful for cleaning up when a process is finished using \fBTcl\fR but
@@ -64,10 +72,20 @@ However, to ensure portability, your code should always invoke
 \fBTcl_Finalize\fR when \fBTcl\fR is being unloaded, to ensure that the
 code will work on all platforms. \fBTcl_Finalize\fR can be safely called
 more than once.
+.PP
+.VS
+\fBTcl_ExitThread\fR is used to terminate the current thread and invoke
+per-thread exit handlers.  This finalization is done by
+\fBTcl_FinalizeThread\fR, which you can call if you just want to clean
+up per-thread state and invoke the thread exit handlers.
+\fBTcl_Finalize\fR calls \fBTcl_FinalizeThread\fR for the current
+thread automatically.
 .VE
 .PP
 \fBTcl_CreateExitHandler\fR arranges for \fIproc\fR to be invoked
 by \fBTcl_Finalize\fR and \fBTcl_Exit\fR.
+\fBTcl_CreateThreadExitHandler\fR arranges for \fIproc\fR to be invoked
+by \fBTcl_FinalizeThread\fR and \fBTcl_ExitThread\fR.
 This provides a hook for cleanup operations such as flushing buffers
 and freeing global memory.
 \fIProc\fR should match the type \fBTcl_ExitProc\fR:
@@ -76,16 +94,18 @@ typedef void Tcl_ExitProc(ClientData \fIclientData\fR);
 .CE
 The \fIclientData\fR parameter to \fIproc\fR is a
 copy of the \fIclientData\fR argument given to
-\fBTcl_CreateExitHandler\fR when the callback
+\fBTcl_CreateExitHandler\fR or \fBTcl_CreateThreadExitHandler\fR when
+the callback
 was created.  Typically, \fIclientData\fR points to a data
 structure containing application-specific information about
 what to do in \fIproc\fR.
 .PP
-\fBTcl_DeleteExitHandler\fR may be called to delete a
+\fBTcl_DeleteExitHandler\fR and \fBTcl_DeleteThreadExitHandler\fR may be
+called to delete a
 previously-created exit handler.  It removes the handler
 indicated by \fIproc\fR and \fIclientData\fR so that no call
 to \fIproc\fR will be made.  If no such handler exists then
-\fBTcl_DeleteExitHandler\fR does nothing.
+\fBTcl_DeleteExitHandler\fR or \fBTcl_DeleteThreadExitHandler\fR does nothing.
 .PP
 .VS
 .PP
@@ -98,6 +118,14 @@ If extension \fBA\fR registers its exit handlers before loading extension
 \fBB\fR, this ensures that any exit handlers for \fBB\fR will be executed
 before the exit handlers for \fBA\fR.
 .VE
+.VS
+.PP
+\fBTcl_Finalize\fR and \fBTcl_Exit\fR call \fBTcl_FinalizeThread\fR 
+and the thread exit handlers \fIafter\fR
+the process-wide exit handlers.  This is because thread finalization shuts
+down the I/O channel system, so any attempt at I/O by the global exit
+handlers will vanish into the bitbucket.
+.VE
 
 .SH KEYWORDS
-callback, cleanup, dynamic loading, end application, exit, unloading
+callback, cleanup, dynamic loading, end application, exit, unloading, thread