diff options
Diffstat (limited to 'doc/Thread.3')
| -rw-r--r-- | doc/Thread.3 | 175 |
1 files changed, 103 insertions, 72 deletions
diff --git a/doc/Thread.3 b/doc/Thread.3 index f65c6e3..5966a71 100644 --- a/doc/Thread.3 +++ b/doc/Thread.3 @@ -4,14 +4,12 @@ '\" '\" 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.14 2002/07/01 18:24:39 jenglish Exp $ -'\" -.so man.macros +'\" .TH Threads 3 "8.1" Tcl "Tcl Library Procedures" +.so man.macros .BS .SH NAME -Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize, Tcl_CreateThread, Tcl_JoinThread \- Tcl thread support. +Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize, Tcl_CreateThread, Tcl_JoinThread \- Tcl thread support .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -38,19 +36,19 @@ void \fBTcl_MutexFinalize\fR(\fImutexPtr\fR) .sp int -\fBTcl_CreateThread\fR(\fIidPtr, threadProc, clientData, stackSize, flags\fR) +\fBTcl_CreateThread\fR(\fIidPtr, proc, clientData, stackSize, flags\fR) .sp int \fBTcl_JoinThread\fR(\fIid, result\fR) .SH ARGUMENTS -.AS Tcl_ThreadDataKey *keyPtr +.AS Tcl_CreateThreadProc proc out .AP Tcl_Condition *condPtr in A condition variable, which must be associated with a mutex lock. -.AP Tcl_Condition *mutexPtr in +.AP Tcl_Mutex *mutexPtr in A mutex lock. -.AP Tcl_Time *timePtr in +.AP "const 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. +Note that a polling value of 0 seconds does not 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 @@ -64,15 +62,15 @@ The referred storage will contain the id of the newly created thread as returned by the operating system. .AP Tcl_ThreadId id in Id of the thread waited upon. -.AP Tcl_ThreadCreateProc threadProc in +.AP Tcl_ThreadCreateProc *proc in This procedure will act as the \fBmain()\fR of the newly created thread. The specified \fIclientData\fR will be its sole argument. .AP ClientData clientData in -Arbitrary information. Passed as sole argument to the \fIthreadProc\fR. +Arbitrary information. Passed as sole argument to the \fIproc\fR. .AP int stackSize in The size of the stack given to the new thread. .AP int flags in -Bitmask containing flags allowing the caller to modify behaviour of +Bitmask containing flags allowing the caller to modify behavior of the new thread. .AP int *result out The referred storage is used to place the exit code of the thread @@ -81,43 +79,40 @@ waited upon into it. .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. +customizing the Tcl core. Starting with the 8.6 release, Tcl +multithreading support is on by default. To disable Tcl multithreading +support, you must include the \fB\-\|\-disable-threads\fR option to +\fBconfigure\fR when you configure and compile your Tcl core. .PP An important constraint 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 -.VS 8.3.1 -Tcl does provide \fBTcl_CreateThread\fR for creating threads. The +the same Tcl interpreter. (However, a single thread can safely create +and use multiple interpreters.) +.SH DESCRIPTION +Tcl provides \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 +modify the behavior through the supplied \fIflags\fR. The value \fBTCL_THREAD_STACK_DEFAULT\fR for the \fIstackSize\fR indicates that the default size as specified by the operating system is to be used -for the new thread. As for the flags, currently are only the values -\fBTCL_THREAD_NOFLAGS\fR and \fBTCL_THREAD_JOINABLE\fR defined. The -first of them invokes the default behaviour with no -specialties. Using the second value marks the new thread as -\fIjoinable\fR. This means that another thread can wait for the such -marked thread to exit and join it. -.PP -Restrictions: On some unix systems the pthread-library does not -contain the functionality to specify the stacksize of a thread. The -specified value for the stacksize is ignored on these systems. Both -Windows and Macintosh currently do not support joinable threads. This -flag value is therefore ignored on these platforms. -.VE -.PP -Tcl does provide \fBTcl_ExitThread\fR and \fBTcl_FinalizeThread\fR +for the new thread. As for the flags, currently only the values +\fBTCL_THREAD_NOFLAGS\fR and \fBTCL_THREAD_JOINABLE\fR are defined. The +first of them invokes the default behavior with no special settings. +Using the second value marks the new thread as \fIjoinable\fR. This +means that another thread can wait for the such marked thread to exit +and join it. +.PP +Restrictions: On some UNIX systems the pthread-library does not +contain the functionality to specify the stack size of a thread. The +specified value for the stack size is ignored on these systems. +Windows currently does not support joinable threads. This +flag value is therefore ignored on this platform. +.PP +Tcl provides the \fBTcl_ExitThread\fR and \fBTcl_FinalizeThread\fR functions 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,32 +124,29 @@ thread which already exited is possible, the system will retain the 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 +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. +.SS "SYNCHRONIZATION AND COMMUNICATION" Tcl provides \fBTcl_ThreadQueueEvent\fR and \fBTcl_ThreadAlert\fR -for handling event queueing in multithreaded applications. See +for handling event queuing 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 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. +For declaration of mutexes the \fBTCL_DECLARE_MUTEX\fR macro should be used. +This macro assures correct mutex handling even when the core is compiled +without 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 @@ -172,40 +164,79 @@ 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 -.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 +.SS INITIALIZATION .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 -All of these synchronization objects are self initializing. +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 -.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 "SCRIPT-LEVEL ACCESS TO THREADS" +.PP +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. +.SH EXAMPLE +.PP +To create a thread with portable code, its implementation function should be +declared as follows: +.PP +.CS +static \fBTcl_ThreadCreateProc\fR MyThreadImplFunc; +.CE +.PP +It should then be defined like this example, which just counts up to a given +value and then finishes. +.PP +.CS +static \fBTcl_ThreadCreateType\fR +MyThreadImplFunc( + ClientData clientData) +{ + int i, limit = (int) clientData; + for (i=0 ; i<limit ; i++) { + /* doing nothing at all here */ + } + \fBTCL_THREAD_CREATE_RETURN\fR; +} +.CE +.PP +To create the above thread, make it execute, and wait for it to finish, we +would do this: +.PP +.CS +int limit = 1000000000; +ClientData limitData = (void*)((intptr_t) limit); +Tcl_ThreadId id; \fI/* holds identity of thread created */\fR +int result; + +if (\fBTcl_CreateThread\fR(&id, MyThreadImplFunc, limitData, + \fBTCL_THREAD_STACK_DEFAULT\fR, + \fBTCL_THREAD_JOINABLE\fR) != TCL_OK) { + \fI/* Thread did not create correctly */\fR + return; +} +\fI/* Do something else for a while here */\fR +if (\fBTcl_JoinThread\fR(id, &result) != TCL_OK) { + \fI/* Thread did not finish properly */\fR + return; +} +\fI/* All cleaned up nicely */\fR +.CE .SH "SEE ALSO" -Tcl_GetCurrentThread, Tcl_ThreadQueueEvent, Tcl_ThreadAlert, -Tcl_ExitThread, Tcl_FinalizeThread, -Tcl_CreateThreadExitHandler, Tcl_DeleteThreadExitHandler +Tcl_GetCurrentThread(3), Tcl_ThreadQueueEvent(3), Tcl_ThreadAlert(3), +Tcl_ExitThread(3), Tcl_FinalizeThread(3), Tcl_CreateThreadExitHandler(3), +Tcl_DeleteThreadExitHandler(3), Thread .SH KEYWORDS thread, mutex, condition variable, thread local storage |