Attachment "932527.patch" to
ticket [932527ffff]
added by
dgp
2004-04-26 07:03:37.
Index: doc/Thread.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/Thread.3,v
retrieving revision 1.16
diff -u -r1.16 Thread.3
--- doc/Thread.3 16 Apr 2004 20:44:18 -0000 1.16
+++ doc/Thread.3 26 Apr 2004 00:01:33 -0000
@@ -92,7 +92,6 @@
releases, a single thread can safely create and use multiple
interpreters.)
.PP
-.VS 8.3.1
Tcl does provide \fBTcl_CreateThread\fR for creating threads. The
caller can determine the size of the stack given to the new thread and
modify the behaviour through the supplied \fIflags\fR. The value
@@ -110,14 +109,12 @@
specified value for the stacksize is ignored on these systems.
Windows currently does not support joinable threads. This
flag value is therefore ignored on this platform.
-.VE
.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
-.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
@@ -129,30 +126,27 @@
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.
.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.
+.VS 8.5
+Tcl provides no built-in commands for scripts to use to create, manage,
+or join threads, nor any script-level access to mutex or condition variables.
+It provides such facilities only via C interfaces, and leaves it up to
+packages to expose these matters to the script level. One such package
+is the \fBThread\fR package.
+.VE 8.5
.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
block until \fBTcl_MutexUnlock\fR is called.
-.VS
A mutex can be destroyed after its use by calling \fBTcl_MutexFinalize\fR.
The result of locking a mutex twice from the same thread is undefined.
On some platforms it will result in a deadlock.
-.VE
The \fBTcl_MutexLock\fR, \fBTcl_MutexUnlock\fR and \fBTcl_MutexFinalize\fR
procedures are defined as empty macros if not compiling with threads enabled.
.PP
@@ -172,14 +166,12 @@
notifications by calling \fBTcl_ConditionWait\fR within a while loop
that tests some invariant.
.PP
-.VS
A condition variable can be destroyed after its use by calling
\fBTcl_ConditionFinalize\fR.
.PP
The \fBTcl_ConditionNotify\fR, \fBTcl_ConditionWait\fR and
\fBTcl_ConditionFinalize\fR procedures are defined as empty macros if
not compiling with threads enabled.
-.VE
.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
@@ -192,20 +184,13 @@
They are implemented as opaque pointers that should be NULL
upon first use.
The mutexes and condition variables are
-.VS
either cleaned up by process exit handlers (if living that long) or
explicitly by calls to \fBTcl_MutexFinalize\fR or
\fBTcl_ConditionFinalize\fR.
-.VE
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 "SEE ALSO"
Tcl_GetCurrentThread, Tcl_ThreadQueueEvent, Tcl_ThreadAlert,
Tcl_ExitThread, Tcl_FinalizeThread,
-Tcl_CreateThreadExitHandler, Tcl_DeleteThreadExitHandler
+Tcl_CreateThreadExitHandler, Tcl_DeleteThreadExitHandler, Thread
.SH KEYWORDS
thread, mutex, condition variable, thread local storage
