* Merged changes from 8.1.0 branch

1 files changed, 44 insertions, 21 deletions

diff --git a/doc/Thread.3 b/doc/Thread.3
index b5321c4..8a4c566 100644
--- a/doc/Thread.3
+++ b/doc/Thread.3
@@ -1,16 +1,17 @@
 '\"
+'\" Copyright (c) 1999 Scriptics Corporation
 '\" Copyright (c) 1998 Sun Microsystems, Inc.
 '\"
 '\" 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.4 1999/04/21 21:50:22 rjohnson Exp $
+'\" RCS: @(#) $Id: Thread.3,v 1.5 1999/04/30 22:45:00 stanton Exp $
 '\" 
 .so man.macros
-.TH Tcl_ConditionNotify 3 "8.1" Tcl "Tcl Library Procedures"
+.TH Threads 3 "8.1" Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock \- thread synchronization support.
+Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock \- Tcl thread support.
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -21,10 +22,7 @@ void
 void
 \fBTcl_ConditionWait\fR(\fIcondPtr, mutexPtr, timePtr\fR)
 .sp
-Tcl_ThreadId
-\fBTcl_GetCurrentThread\fR()
-.sp
-VOID *
+Void *
 \fBTcl_GetThreadData\fR(\fIkeyPtr, size\fR)
 .sp
 void
@@ -32,10 +30,6 @@ void
 .sp
 void
 \fBTcl_MutexUnlock\fR(\fImutexPtr\fR)
-.sp
-\fBTcl_ThreadAlert\fR(\fIthreadId\fR)
-.sp
-\fBTcl_ThreadQueueEvent\fR(\fIthreadId, evPtr, position\fR)
 .SH ARGUMENTS
 .AS Tcl_ThreadDataKey *keyPtr
 .AP Tcl_Condition *condPtr in
@@ -54,9 +48,42 @@ The size of the thread local storage block.  This amount of data
 is allocated and initialized to zero the first time each thread
 calls \fBTcl_GetThreadData\fR.
 .BE
-
-.SH DESCRIPTION
+.SH INTRODUCTION
+Beginning with the 8.1 release, the Tcl core is thread safe, which
+allows you to incorporate Tcl into multithreaded applications without
+customizing the Tcl core.  To enable Tcl multithreading support,
+you must include the \fB--enable-threads\fR option to \fBconfigure\fR
+when you configure and compile your Tcl core.
+.PP
+An important contstraint of the Tcl threads implementation is that
+\fIonly the thread that created a Tcl interpreter can use that
+interpreter\fR.  In other words, multiple threads can not access
+the same Tcl interpreter.  (However, as was the case in previous
+releases, a single thread can safely create and use multiple
+interpreters.)
+.PP
+Tcl provides no special API for creating
+threads.  When writing multithreaded applications incorporating Tcl,
+use the standard POSIX threads APIs on Unix systems and the standard
+Win32 threads APIs on Windows systems.
 .PP
+Tcl does provide \fBTcl_ExitThread\fR and \fBTcl_FinalizeThread\fR
+for terminating threads and invoking optional per-thread exit
+handlers.  See the \fBTcl_Exit\fR page for more information on these
+procedures.
+.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.
+.PP
+In this release, the Tcl language itself provides no support for
+creating multithreaded scripts (for example, scripts that could spawn
+a Tcl interpreter in a separate thread).  If you need to add this
+feature at this time, see the \fItclThreadTest.c\fR
+file in the Tcl source distribution for an experimental implementation
+of a Tcl "Thread" package implementing thread creation and management
+commands at the script level.
+.SH DESCRIPTION
 A mutex is a lock that is used to serialize all threads through a piece
 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
@@ -84,13 +111,6 @@ 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
-The \fBTcl_GetCurrentThread\fR call returns the thread Id of the
-thread in which the call is made.  The thread Id can be used in calls
-to \fBTcl_ThreadQueueEvent\fR and \fBTcl_ThreadAlert\fR.  These
-procedures are essentially mutex-protected vesions of
-\fBTcl_AlertNotifier\fR and \fBTcl_QueueEvent\fR, respectively.  See
-the manual entry for \fBNotifier\fR for more details.
-.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 
@@ -98,7 +118,6 @@ allocated and initialized to all zeros the first time each thread asks for it.
 The storage is automatically deallocated by \fBTcl_FinalizeThread\fR.
 .SH INITIALIZATION
 .PP
-.PP
 All of these synchronization objects are self initializing.
 They are implemented as opaque pointers that should be NULL
 upon first use.
@@ -110,5 +129,9 @@ The API to create threads is not finalized at this time.
 There are private facilities to create threads that contain a new
 Tcl interpreter, and to send scripts among threads.
 Dive into tclThreadTest.c and tclThread.c for examples.
+.SH "SEE ALSO"
+Tcl_GetCurrentThread, Tcl_ThreadQueueEvent, Tcl_ThreadAlert,
+Tcl_ExitThread, Tcl_FinalizeThread,
+Tcl_CreateThreadExitHandler, Tcl_DeleteThreadExitHandler
 .SH KEYWORDS
 thread, mutex, condition variable, thread local storage