summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorkupries <kupries>2000-04-09 16:04:16 (GMT)
committerkupries <kupries>2000-04-09 16:04:16 (GMT)
commitefe824c8141a780f310fc5aef29a013f53fe541c (patch)
tree939d56df2b9aea3e08214838f501affff23a3ff4 /doc
parent5551a23a1a0fbd1e5febaa29157e06e883049475 (diff)
downloadtcl-efe824c8141a780f310fc5aef29a013f53fe541c.zip
tcl-efe824c8141a780f310fc5aef29a013f53fe541c.tar.gz
tcl-efe824c8141a780f310fc5aef29a013f53fe541c.tar.bz2
2000-04-08 Andreas Kupries <a.kupries@westend.com>
* Overall change: Definition of a public API for the creation of new threads. * generic/tclInt.h (line 1802f): Removed the definition of 'TclpThreadCreate'. (line 793f) Removed the definition of 'Tcl_ThreadCreateProc'. * generic/tcl.h (line 388f): Readded the definition of 'Tcl_ThreadCreateProc'. Added Win32 stuff send in by David Graveraux <davygrvy@bigfoot.com> to that too (__stdcall, ...). Added macros for the default stacksize and allowed flags. * generic/tcl.decls (line 1356f): Added definition of 'Tcl_CreateThread', slot 393 of the stub table. Two new arguments in the public API, for stacksize and flags. * win/tclWinThrd.c: * mac/tclMacThrd.c: Renamed TclpThreadCreate to Tcl_CreateThread, added handling of the stacksize. Flags are currently ignored. * unix/tclUnixThrd.c: See above, but handles joinable flag. Ignores the specified stacksize if the macro HAVE_PTHREAD_ATTR_SETSTACKSIZE is not defined. * generic/tclThreadTest.c (line 363): See below. * unix/tclUnixNotfy.c (line 210): Adapted to the changes above. Uses default stacksize and no flags now. * unic/tcl.m4 (line 382f): Added a check for 'pthread_attr_setstacksize' to detect platforms not implementing this feature of pthreads. If it is implemented, configure will define the macro HAVE_PTHREAD_ATTR_SETSTACKSIZE (See unix/tclUnixThrd.c too). * doc/Thread.3: Added Tcl_CreateThread and its arguments to the list of described functions. Removed stuff about not providing a public C-API for thread-creation.
Diffstat (limited to 'doc')
-rw-r--r--doc/Thread.341
1 files changed, 36 insertions, 5 deletions
diff --git a/doc/Thread.3 b/doc/Thread.3
index cd50dbc..3ba95b2 100644
--- a/doc/Thread.3
+++ b/doc/Thread.3
@@ -5,7 +5,7 @@
'\" 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.8 2000/04/04 20:28:40 kupries Exp $
+'\" RCS: @(#) $Id: Thread.3,v 1.9 2000/04/09 16:04:17 kupries Exp $
'\"
.so man.macros
.TH Threads 3 "8.1" Tcl "Tcl Library Procedures"
@@ -38,6 +38,9 @@ void
.sp
void
\fBTcl_MutexFinalize\fR(\fImutexPtr\fR)
+.sp
+int
+\fBTcl_CreateThread\fR(\fIidPtr, threadProc, clientData, stackSize, flags\fR)
.SH ARGUMENTS
.AS Tcl_ThreadDataKey *keyPtr
.AP Tcl_Condition *condPtr in
@@ -55,6 +58,19 @@ a different block of storage with this key.
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 refered storage will contain the id of the newly created thread as
+returned by the operating system.
+.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.
.BE
.SH INTRODUCTION
Beginning with the 8.1 release, the Tcl core is thread safe, which
@@ -70,10 +86,25 @@ 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.
+.VB
+Tcl does provide \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 are only the values
+\fBTCL_THREAD_NOFLAGS\fR and \fBTCL_THREAD_JOINABLE\fR defined. The
+first of them invokes the default behaviour with no
+specialities. 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.
+
+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 terminating threads and invoking optional per-thread exit