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.

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