merged tcl 8.1 branch back into the main trunk

1 files changed, 100 insertions, 0 deletions

diff --git a/doc/Thread.3 b/doc/Thread.3
new file mode 100644
index 0000000..595fac3
--- /dev/null
+++ b/doc/Thread.3
@@ -0,0 +1,100 @@
+'\"
+'\" 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.2 1999/04/16 00:46:33 stanton Exp $
+'\" 
+.so man.macros
+.TH Tcl_ConditionNotify 3 "8.1" Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock \- thread synchronization support.
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+void
+\fBTcl_ConditionNotify\fR(\fIcondPtr\fR)
+.sp
+void
+\fBTcl_ConditionWait\fR(\fIcondPtr, mutexPtr, timePtr\fR)
+.sp
+VOID *
+\fBTcl_GetThreadData\fR(\fIkeyPtr, size\fR)
+.sp
+void
+\fBTcl_MutexLock\fR(\fImutexPtr\fR)
+.sp
+void
+\fBTcl_MutexUnlock\fR(\fImutexPtr\fR)
+.SH ARGUMENTS
+.AS Tcl_ThreadDataKey *keyPtr
+.AP Tcl_Condition *condPtr in
+A condition variable, which must be associated with a mutex lock.
+.AP Tcl_Condition *mutexPtr in
+A mutex lock.
+.AP Tcl_Time *timePtr in
+A time limit on the condition wait.  NULL to wait forever.
+Note that a polling value of 0 seconds doesn't make much sense.
+.AP Tcl_ThreadDataKey *keyPtr in
+This identifies a block of thread local storage.  The key should be
+static and process-wide, yet each thread will end up associating
+a different block of storage with this key.
+.AP int *size in
+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
+.PP
+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
+block until \fBTcl_MutexUnlock\fR is called.
+.VS
+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
+procedures are defined as empty macros if not compiling with threads enabled.
+.PP
+A condition variable is used as a signaling mechanism:
+a thread can lock a mutex and then wait on a condition variable
+with \fBTcl_ConditionWait\fR.  This atomically releases the mutex lock
+and blocks the waiting thread until another thread calls
+\fBTcl_ConditionNotify\fR.  The caller of \fBTcl_ConditionNotify\fR should
+have the associated mutex held by previously calling \fBTcl_MutexLock\fR,
+but this is not enforced.  Notifying the
+condition variable unblocks all threads waiting on the condition variable,
+but they do not proceed until the mutex is released with \fBTcl_MutexUnlock\fR.
+The implementation of \fBTcl_ConditionWait\fR automatically locks
+the mutex before returning.
+.PP
+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_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 
+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.
+The mutexes and condition variables are
+cleaned up by process exit handlers.  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
+Tcl interpreter, and to send scripts among threads.
+Dive into tclThreadTest.c and tclThread.c for examples.
+.SH KEYWORDS
+thread, mutex, condition variable, thread local storage