diff options
Diffstat (limited to 'doc/Thread.3')
-rw-r--r-- | doc/Thread.3 | 394 |
1 files changed, 197 insertions, 197 deletions
diff --git a/doc/Thread.3 b/doc/Thread.3 index 28aa635..766d7ad 100644 --- a/doc/Thread.3 +++ b/doc/Thread.3 @@ -1,197 +1,197 @@ -'\"
-'\" 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.26 2007/10/29 11:28:50 dkf Exp $
-'\"
-.so man.macros
-.TH Threads 3 "8.1" Tcl "Tcl Library Procedures"
-.BS
-.SH NAME
-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
-.sp
-void
-\fBTcl_ConditionNotify\fR(\fIcondPtr\fR)
-.sp
-void
-\fBTcl_ConditionWait\fR(\fIcondPtr, mutexPtr, timePtr\fR)
-.sp
-void
-\fBTcl_ConditionFinalize\fR(\fIcondPtr\fR)
-.sp
-Void *
-\fBTcl_GetThreadData\fR(\fIkeyPtr, size\fR)
-.sp
-void
-\fBTcl_MutexLock\fR(\fImutexPtr\fR)
-.sp
-void
-\fBTcl_MutexUnlock\fR(\fImutexPtr\fR)
-.sp
-void
-\fBTcl_MutexFinalize\fR(\fImutexPtr\fR)
-.sp
-int
-\fBTcl_CreateThread\fR(\fIidPtr, threadProc, clientData, stackSize, flags\fR)
-.sp
-int
-\fBTcl_JoinThread\fR(\fIid, result\fR)
-.SH ARGUMENTS
-.AS Tcl_CreateThreadProc threadProc out
-.AP Tcl_Condition *condPtr in
-A condition variable, which must be associated with a mutex lock.
-.AP Tcl_Mutex *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 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
-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.
-.AP Tcl_ThreadId *idPtr out
-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
-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.
-.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
-the new thread.
-.AP int *result out
-The referred storage is used to place the exit code of the thread
-waited upon into it.
-.BE
-.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 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, 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
-\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 only the values
-\fBTCL_THREAD_NOFLAGS\fR and \fBTCL_THREAD_JOINABLE\fR are 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 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
-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
-its creation via \fBTcl_CreateThread\fR.
-.PP
-Trying to wait for the exit of a non-joinable thread or a thread which
-is already waited upon will result in an error. Waiting for a joinable
-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.
-.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 queuing in multithreaded applications. See
-the \fBNotifier\fR manual page for more information on these procedures.
-.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.
-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.
-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
-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
-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.
-.SS INITIALIZATION
-.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
-either cleaned up by process exit handlers (if living that long) or
-explicitly by calls to \fBTcl_MutexFinalize\fR or
-\fBTcl_ConditionFinalize\fR.
-Thread local storage is reclaimed during \fBTcl_FinalizeThread\fR.
-.SH "SCRIPT-LEVEL ACCESS TO THREADS"
-.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 "SEE ALSO"
-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
+'\" +'\" 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.27 2007/10/29 17:17:54 dgp Exp $ +'\" +.so man.macros +.TH Threads 3 "8.1" Tcl "Tcl Library Procedures" +.BS +.SH NAME +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 +.sp +void +\fBTcl_ConditionNotify\fR(\fIcondPtr\fR) +.sp +void +\fBTcl_ConditionWait\fR(\fIcondPtr, mutexPtr, timePtr\fR) +.sp +void +\fBTcl_ConditionFinalize\fR(\fIcondPtr\fR) +.sp +Void * +\fBTcl_GetThreadData\fR(\fIkeyPtr, size\fR) +.sp +void +\fBTcl_MutexLock\fR(\fImutexPtr\fR) +.sp +void +\fBTcl_MutexUnlock\fR(\fImutexPtr\fR) +.sp +void +\fBTcl_MutexFinalize\fR(\fImutexPtr\fR) +.sp +int +\fBTcl_CreateThread\fR(\fIidPtr, threadProc, clientData, stackSize, flags\fR) +.sp +int +\fBTcl_JoinThread\fR(\fIid, result\fR) +.SH ARGUMENTS +.AS Tcl_CreateThreadProc threadProc out +.AP Tcl_Condition *condPtr in +A condition variable, which must be associated with a mutex lock. +.AP Tcl_Mutex *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 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 +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. +.AP Tcl_ThreadId *idPtr out +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 +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. +.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 +the new thread. +.AP int *result out +The referred storage is used to place the exit code of the thread +waited upon into it. +.BE +.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 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, 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 +\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 only the values +\fBTCL_THREAD_NOFLAGS\fR and \fBTCL_THREAD_JOINABLE\fR are 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 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 +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 +its creation via \fBTcl_CreateThread\fR. +.PP +Trying to wait for the exit of a non-joinable thread or a thread which +is already waited upon will result in an error. Waiting for a joinable +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. +.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 queuing in multithreaded applications. See +the \fBNotifier\fR manual page for more information on these procedures. +.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. +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. +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 +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 +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. +.SS INITIALIZATION +.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 +either cleaned up by process exit handlers (if living that long) or +explicitly by calls to \fBTcl_MutexFinalize\fR or +\fBTcl_ConditionFinalize\fR. +Thread local storage is reclaimed during \fBTcl_FinalizeThread\fR. +.SH "SCRIPT-LEVEL ACCESS TO THREADS" +.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 "SEE ALSO" +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 |