summaryrefslogtreecommitdiffstats
path: root/doc/Thread.3
diff options
context:
space:
mode:
Diffstat (limited to 'doc/Thread.3')
-rw-r--r--doc/Thread.365
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