"Fossies" - the Fresh Open Source Software Archive

Member "SAOImageDS9/tcl8.6/doc/Thread.3" (13 Nov 2019, 9825 Bytes) of package /linux/misc/ds9.8.1.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file.

    1 '\"
    2 '\" Copyright (c) 1999 Scriptics Corporation
    3 '\" Copyright (c) 1998 Sun Microsystems, Inc.
    4 '\"
    5 '\" See the file "license.terms" for information on usage and redistribution
    6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
    7 '\"
    8 .TH Threads 3 "8.1" Tcl "Tcl Library Procedures"
    9 .so man.macros
   10 .BS
   11 .SH NAME
   12 Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize, Tcl_CreateThread, Tcl_JoinThread \- Tcl thread support
   13 .SH SYNOPSIS
   14 .nf
   15 \fB#include <tcl.h>\fR
   16 .sp
   17 void
   18 \fBTcl_ConditionNotify\fR(\fIcondPtr\fR)
   19 .sp
   20 void
   21 \fBTcl_ConditionWait\fR(\fIcondPtr, mutexPtr, timePtr\fR)
   22 .sp
   23 void
   24 \fBTcl_ConditionFinalize\fR(\fIcondPtr\fR)
   25 .sp
   26 Void *
   27 \fBTcl_GetThreadData\fR(\fIkeyPtr, size\fR)
   28 .sp
   29 void
   30 \fBTcl_MutexLock\fR(\fImutexPtr\fR)
   31 .sp
   32 void
   33 \fBTcl_MutexUnlock\fR(\fImutexPtr\fR)
   34 .sp
   35 void
   36 \fBTcl_MutexFinalize\fR(\fImutexPtr\fR)
   37 .sp
   38 int
   39 \fBTcl_CreateThread\fR(\fIidPtr, proc, clientData, stackSize, flags\fR)
   40 .sp
   41 int
   42 \fBTcl_JoinThread\fR(\fIid, result\fR)
   43 .SH ARGUMENTS
   44 .AS Tcl_CreateThreadProc proc out
   45 .AP Tcl_Condition *condPtr in
   46 A condition variable, which must be associated with a mutex lock.
   47 .AP Tcl_Mutex *mutexPtr in
   48 A mutex lock.
   49 .AP "const Tcl_Time" *timePtr in
   50 A time limit on the condition wait.  NULL to wait forever.
   51 Note that a polling value of 0 seconds does not make much sense.
   52 .AP Tcl_ThreadDataKey *keyPtr in
   53 This identifies a block of thread local storage.  The key should be
   54 static and process-wide, yet each thread will end up associating
   55 a different block of storage with this key.
   56 .AP int *size in
   57 The size of the thread local storage block.  This amount of data
   58 is allocated and initialized to zero the first time each thread
   59 calls \fBTcl_GetThreadData\fR.
   60 .AP Tcl_ThreadId *idPtr out
   61 The referred storage will contain the id of the newly created thread as
   62 returned by the operating system.
   63 .AP Tcl_ThreadId id in
   64 Id of the thread waited upon.
   65 .AP Tcl_ThreadCreateProc *proc in
   66 This procedure will act as the \fBmain()\fR of the newly created
   67 thread. The specified \fIclientData\fR will be its sole argument.
   68 .AP ClientData clientData in
   69 Arbitrary information. Passed as sole argument to the \fIproc\fR.
   70 .AP int stackSize in
   71 The size of the stack given to the new thread.
   72 .AP int flags in
   73 Bitmask containing flags allowing the caller to modify behavior of
   74 the new thread.
   75 .AP int *result out
   76 The referred storage is used to place the exit code of the thread
   77 waited upon into it.
   78 .BE
   79 .SH INTRODUCTION
   80 Beginning with the 8.1 release, the Tcl core is thread safe, which
   81 allows you to incorporate Tcl into multithreaded applications without
   82 customizing the Tcl core.  Starting with the 8.6 release, Tcl
   83 multithreading support is on by default. To disable Tcl multithreading
   84 support, you must include the \fB\-\|\-disable-threads\fR option to
   85 \fBconfigure\fR when you configure and compile your Tcl core.
   86 .PP
   87 An important constraint of the Tcl threads implementation is that
   88 \fIonly the thread that created a Tcl interpreter can use that
   89 interpreter\fR.  In other words, multiple threads can not access
   90 the same Tcl interpreter.  (However, a single thread can safely create
   91 and use multiple interpreters.)
   92 .SH DESCRIPTION
   93 Tcl provides \fBTcl_CreateThread\fR for creating threads. The
   94 caller can determine the size of the stack given to the new thread and
   95 modify the behavior through the supplied \fIflags\fR. The value
   96 \fBTCL_THREAD_STACK_DEFAULT\fR for the \fIstackSize\fR indicates that
   97 the default size as specified by the operating system is to be used
   98 for the new thread. As for the flags, currently only the values
   99 \fBTCL_THREAD_NOFLAGS\fR and \fBTCL_THREAD_JOINABLE\fR are defined. The
  100 first of them invokes the default behavior with no special settings.
  101 Using the second value marks the new thread as \fIjoinable\fR. This
  102 means that another thread can wait for the such marked thread to exit
  103 and join it.
  104 .PP
  105 Restrictions: On some UNIX systems the pthread-library does not
  106 contain the functionality to specify the stack size of a thread. The
  107 specified value for the stack size is ignored on these systems.
  108 Windows currently does not support joinable threads. This
  109 flag value is therefore ignored on this platform.
  110 .PP
  111 Tcl provides the \fBTcl_ExitThread\fR and \fBTcl_FinalizeThread\fR functions
  112 for terminating threads and invoking optional per-thread exit
  113 handlers.  See the \fBTcl_Exit\fR page for more information on these
  114 procedures.
  115 .PP
  116 The \fBTcl_JoinThread\fR function is provided to allow threads to wait
  117 upon the exit of another thread, which must have been marked as
  118 joinable through usage of the \fBTCL_THREAD_JOINABLE\fR-flag during
  119 its creation via \fBTcl_CreateThread\fR.
  120 .PP
  121 Trying to wait for the exit of a non-joinable thread or a thread which
  122 is already waited upon will result in an error. Waiting for a joinable
  123 thread which already exited is possible, the system will retain the
  124 necessary information until after the call to \fBTcl_JoinThread\fR.
  125 This means that not calling \fBTcl_JoinThread\fR for a joinable thread
  126 will cause a memory leak.
  127 .PP
  128 The \fBTcl_GetThreadData\fR call returns a pointer to a block of
  129 thread-private data.  Its argument is a key that is shared by all threads
  130 and a size for the block of storage.  The storage is automatically
  131 allocated and initialized to all zeros the first time each thread asks for it.
  132 The storage is automatically deallocated by \fBTcl_FinalizeThread\fR.
  133 .SS "SYNCHRONIZATION AND COMMUNICATION"
  134 Tcl provides \fBTcl_ThreadQueueEvent\fR and \fBTcl_ThreadAlert\fR
  135 for handling event queuing in multithreaded applications.  See
  136 the \fBNotifier\fR manual page for more information on these procedures.
  137 .PP
  138 A mutex is a lock that is used to serialize all threads through a piece
  139 of code by calling \fBTcl_MutexLock\fR and \fBTcl_MutexUnlock\fR.
  140 If one thread holds a mutex, any other thread calling \fBTcl_MutexLock\fR will
  141 block until \fBTcl_MutexUnlock\fR is called.
  142 A mutex can be destroyed after its use by calling \fBTcl_MutexFinalize\fR.
  143 The result of locking a mutex twice from the same thread is undefined.
  144 On some platforms it will result in a deadlock.
  145 The \fBTcl_MutexLock\fR, \fBTcl_MutexUnlock\fR and \fBTcl_MutexFinalize\fR
  146 procedures are defined as empty macros if not compiling with threads enabled.
  147 For declaration of mutexes the \fBTCL_DECLARE_MUTEX\fR macro should be used.
  148 This macro assures correct mutex handling even when the core is compiled
  149 without threads enabled.
  150 .PP
  151 A condition variable is used as a signaling mechanism:
  152 a thread can lock a mutex and then wait on a condition variable
  153 with \fBTcl_ConditionWait\fR.  This atomically releases the mutex lock
  154 and blocks the waiting thread until another thread calls
  155 \fBTcl_ConditionNotify\fR.  The caller of \fBTcl_ConditionNotify\fR should
  156 have the associated mutex held by previously calling \fBTcl_MutexLock\fR,
  157 but this is not enforced.  Notifying the
  158 condition variable unblocks all threads waiting on the condition variable,
  159 but they do not proceed until the mutex is released with \fBTcl_MutexUnlock\fR.
  160 The implementation of \fBTcl_ConditionWait\fR automatically locks
  161 the mutex before returning.
  162 .PP
  163 The caller of \fBTcl_ConditionWait\fR should be prepared for spurious
  164 notifications by calling \fBTcl_ConditionWait\fR within a while loop
  165 that tests some invariant.
  166 .PP
  167 A condition variable can be destroyed after its use by calling
  168 \fBTcl_ConditionFinalize\fR.
  169 .PP
  170 The \fBTcl_ConditionNotify\fR, \fBTcl_ConditionWait\fR and
  171 \fBTcl_ConditionFinalize\fR procedures are defined as empty macros if
  172 not compiling with threads enabled.
  173 .SS INITIALIZATION
  174 .PP
  175 All of these synchronization objects are self-initializing.
  176 They are implemented as opaque pointers that should be NULL
  177 upon first use.
  178 The mutexes and condition variables are
  179 either cleaned up by process exit handlers (if living that long) or
  180 explicitly by calls to \fBTcl_MutexFinalize\fR or
  181 \fBTcl_ConditionFinalize\fR.
  182 Thread local storage is reclaimed during \fBTcl_FinalizeThread\fR.
  183 .SH "SCRIPT-LEVEL ACCESS TO THREADS"
  184 .PP
  185 Tcl provides no built-in commands for scripts to use to create,
  186 manage, or join threads, nor any script-level access to mutex or
  187 condition variables.  It provides such facilities only via C
  188 interfaces, and leaves it up to packages to expose these matters to
  189 the script level.  One such package is the \fBThread\fR package.
  190 .SH EXAMPLE
  191 .PP
  192 To create a thread with portable code, its implementation function should be
  193 declared as follows:
  194 .PP
  195 .CS
  196 static \fBTcl_ThreadCreateProc\fR MyThreadImplFunc;
  197 .CE
  198 .PP
  199 It should then be defined like this example, which just counts up to a given
  200 value and then finishes.
  201 .PP
  202 .CS
  203 static \fBTcl_ThreadCreateType\fR
  204 MyThreadImplFunc(
  205     ClientData clientData)
  206 {
  207     int i, limit = (int) clientData;
  208     for (i=0 ; i<limit ; i++) {
  209         /* doing nothing at all here */
  210     }
  211     \fBTCL_THREAD_CREATE_RETURN\fR;
  212 }
  213 .CE
  214 .PP
  215 To create the above thread, make it execute, and wait for it to finish, we
  216 would do this:
  217 .PP
  218 .CS
  219 int limit = 1000000000;
  220 ClientData limitData = (void*)((intptr_t) limit);
  221 Tcl_ThreadId id;    \fI/* holds identity of thread created */\fR
  222 int result;
  223 
  224 if (\fBTcl_CreateThread\fR(&id, MyThreadImplFunc, limitData,
  225         \fBTCL_THREAD_STACK_DEFAULT\fR,
  226         \fBTCL_THREAD_JOINABLE\fR) != TCL_OK) {
  227     \fI/* Thread did not create correctly */\fR
  228     return;
  229 }
  230 \fI/* Do something else for a while here */\fR
  231 if (\fBTcl_JoinThread\fR(id, &result) != TCL_OK) {
  232     \fI/* Thread did not finish properly */\fR
  233     return;
  234 }
  235 \fI/* All cleaned up nicely */\fR
  236 .CE
  237 .SH "SEE ALSO"
  238 Tcl_GetCurrentThread(3), Tcl_ThreadQueueEvent(3), Tcl_ThreadAlert(3),
  239 Tcl_ExitThread(3), Tcl_FinalizeThread(3), Tcl_CreateThreadExitHandler(3),
  240 Tcl_DeleteThreadExitHandler(3), Thread
  241 .SH KEYWORDS
  242 thread, mutex, condition variable, thread local storage