summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2010-03-31 14:14:04 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2010-03-31 14:14:04 (GMT)
commitcba938f2dc8da1903c146685526669dcbc31ed43 (patch)
tree16d675a281006bfbde65c2553ba37ec414900236
parentd939798dd89166dee8a80e460ca723c718099d64 (diff)
downloadtcl-cba938f2dc8da1903c146685526669dcbc31ed43.zip
tcl-cba938f2dc8da1903c146685526669dcbc31ed43.tar.gz
tcl-cba938f2dc8da1903c146685526669dcbc31ed43.tar.bz2
Improve the documentation of how to make and use a thread.
-rw-r--r--ChangeLog18
-rw-r--r--doc/Thread.349
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),