line endings

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