diff options
| -rw-r--r-- | ChangeLog | 18 | ||||
| -rw-r--r-- | doc/Thread.3 | 49 |
2 files changed, 60 insertions, 7 deletions
@@ -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), |