From cba938f2dc8da1903c146685526669dcbc31ed43 Mon Sep 17 00:00:00 2001
From: dkf <donal.k.fellows@manchester.ac.uk>
Date: Wed, 31 Mar 2010 14:14:04 +0000
Subject: Improve the documentation of how to make and use a thread.

---
 ChangeLog    | 18 ++++++++++++------
 doc/Thread.3 | 49 ++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 60 insertions(+), 7 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 73442ef..229d1fe 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2010-03-31  Donal K. Fellows  <dkf@users.sf.net>
+
+	* doc/Thread.3: Added some better documentation of how to create and
+	use a thread using the C-level thread API, based on realization that
+	no such tutorial appeared to exist.
+
 2010-03-31  Jan Nijtmans  <nijtmans@users.sf.net>
 
 	* test/cmdMZ.test:    [FRQ 2974744]: share exception codes (ObjType?):
@@ -8,11 +14,11 @@
 2010-03-30  Andreas Kupries  <andreask@activestate.com>
 
 	* generic/tclIORChan.c (ReflectClose, ReflectInput, ReflectOutput,
-	ReflectSeekWide, ReflectWatch, ReflectBlock, ReflectSetOption,
-	ReflectGetOption, ForwardProc): [Bug 2978773]: Preserve
+	(ReflectSeekWide, ReflectWatch, ReflectBlock, ReflectSetOption,
+	(ReflectGetOption, ForwardProc): [Bug 2978773]: Preserve
 	ReflectedChannel* structures across handler invokations, to avoid
-	crashes when the handler implementation induces nested callbacks
-	and destruction of the channel deep inside such a nesting.
+	crashes when the handler implementation induces nested callbacks and
+	destruction of the channel deep inside such a nesting.
 
 2010-03-30  Don Porter  <dgp@users.sourceforge.net>
 
@@ -22,9 +28,9 @@
 
 2010-03-30  Jan Nijtmans  <nijtmans@users.sf.net>
 
-	* generic/tclIndexObj:	[FRQ 2974744]: share exception codes (ObjType?):
+	* generic/tclIndexObj:	[FRQ 2974744]: share exception codes
 	* generic/tclResult.c:	further optimization, making use of indexType.
-	* generic/tclZlib.c     [Bug 2979399] uninitialized value troubles
+	* generic/tclZlib.c     [Bug 2979399]: uninitialized value troubles
 
 2010-03-30  Donal K. Fellows  <dkf@users.sf.net>
 
diff --git a/doc/Thread.3 b/doc/Thread.3
index 97e759a..e5ea559 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.30 2008/07/24 21:54:43 nijtmans Exp $
+'\" RCS: @(#) $Id: Thread.3,v 1.31 2010/03/31 14:14:04 dkf Exp $
 '\" 
 .so man.macros
 .TH Threads 3 "8.1" Tcl "Tcl Library Procedures"
@@ -188,6 +188,53 @@ 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(3), Tcl_ThreadQueueEvent(3), Tcl_ThreadAlert(3),
 Tcl_ExitThread(3), Tcl_FinalizeThread(3), Tcl_CreateThreadExitHandler(3),
-- 
cgit v0.12