diff options
Diffstat (limited to 'doc/Thread.3')
| -rw-r--r-- | doc/Thread.3 | 65 |
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 |