diff options
Diffstat (limited to 'doc/Thread.3')
| -rw-r--r-- | doc/Thread.3 | 62 |
1 files changed, 8 insertions, 54 deletions
diff --git a/doc/Thread.3 b/doc/Thread.3 index 4b5e7c3..5517a41 100644 --- a/doc/Thread.3 +++ b/doc/Thread.3 @@ -5,8 +5,8 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -.so man.macros .TH Threads 3 "8.1" Tcl "Tcl Library Procedures" +.so man.macros .BS .SH NAME Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize, Tcl_CreateThread, Tcl_JoinThread \- Tcl thread support @@ -36,17 +36,17 @@ void \fBTcl_MutexFinalize\fR(\fImutexPtr\fR) .sp int -\fBTcl_CreateThread\fR(\fIidPtr, proc, clientData, stackSize, flags\fR) +\fBTcl_CreateThread\fR(\fIidPtr, threadProc, clientData, stackSize, flags\fR) .sp int \fBTcl_JoinThread\fR(\fIid, result\fR) .SH ARGUMENTS -.AS Tcl_CreateThreadProc proc out +.AS Tcl_CreateThreadProc threadProc out .AP Tcl_Condition *condPtr in A condition variable, which must be associated with a mutex lock. .AP Tcl_Mutex *mutexPtr in A mutex lock. -.AP "const Tcl_Time" *timePtr in +.AP Tcl_Time *timePtr in A time limit on the condition wait. NULL to wait forever. Note that a polling value of 0 seconds does not make much sense. .AP Tcl_ThreadDataKey *keyPtr in @@ -62,11 +62,11 @@ The referred storage will contain the id of the newly created thread as returned by the operating system. .AP Tcl_ThreadId id in Id of the thread waited upon. -.AP Tcl_ThreadCreateProc *proc in +.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 \fIproc\fR. +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 @@ -180,59 +180,13 @@ explicitly by calls to \fBTcl_MutexFinalize\fR or \fBTcl_ConditionFinalize\fR. Thread local storage is reclaimed during \fBTcl_FinalizeThread\fR. .SH "SCRIPT-LEVEL ACCESS TO THREADS" -.PP +.VS 8.5 Tcl provides no built-in commands for scripts to use to create, 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 +.VE 8.5 .SH "SEE ALSO" Tcl_GetCurrentThread(3), Tcl_ThreadQueueEvent(3), Tcl_ThreadAlert(3), Tcl_ExitThread(3), Tcl_FinalizeThread(3), Tcl_CreateThreadExitHandler(3), |