summaryrefslogtreecommitdiffstats
path: root/doc
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 /doc
parentd939798dd89166dee8a80e460ca723c718099d64 (diff)
downloadtcl-cba938f2dc8da1903c146685526669dcbc31ed43.zip
tcl-cba938f2dc8da1903c146685526669dcbc31ed43.tar.gz
tcl-cba938f2dc8da1903c146685526669dcbc31ed43.tar.bz2
Improve the documentation of how to make and use a thread.
Diffstat (limited to 'doc')
-rw-r--r--doc/Thread.349
1 files changed, 48 insertions, 1 deletions
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),