1Threads(3)                  Tcl Library Procedures                  Threads(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize, Tcl_Get‐
9       ThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize, Tcl_Cre‐
10       ateThread, Tcl_JoinThread - Tcl thread support
11

SYNOPSIS

13       #include <tcl.h>
14
15       void
16       Tcl_ConditionNotify(condPtr)
17
18       void
19       Tcl_ConditionWait(condPtr, mutexPtr, timePtr)
20
21       void
22       Tcl_ConditionFinalize(condPtr)
23
24       Void *
25       Tcl_GetThreadData(keyPtr, size)
26
27       void
28       Tcl_MutexLock(mutexPtr)
29
30       void
31       Tcl_MutexUnlock(mutexPtr)
32
33       void
34       Tcl_MutexFinalize(mutexPtr)
35
36       int
37       Tcl_CreateThread(idPtr, threadProc, clientData, stackSize, flags)
38
39       int
40       Tcl_JoinThread(id, result)
41

ARGUMENTS

43       Tcl_Condition *condPtr (in)                   A   condition   variable,
44                                                     which must be  associated
45                                                     with a mutex lock.
46
47       Tcl_Mutex *mutexPtr (in)                      A mutex lock.
48
49       Tcl_Time *timePtr (in)                        A  time limit on the con‐
50                                                     dition  wait.   NULL   to
51                                                     wait  forever.  Note that
52                                                     a polling value of 0 sec‐
53                                                     onds  does  not make much
54                                                     sense.
55
56       Tcl_ThreadDataKey *keyPtr (in)                This identifies  a  block
57                                                     of  thread local storage.
58                                                     The key should be  static
59                                                     and   process-wide,   yet
60                                                     each thread will  end  up
61                                                     associating  a  different
62                                                     block  of  storage   with
63                                                     this key.
64
65       int *size (in)                                The  size  of  the thread
66                                                     local   storage    block.
67                                                     This  amount  of  data is
68                                                     allocated and initialized
69                                                     to  zero  the  first time
70                                                     each     thread     calls
71                                                     Tcl_GetThreadData.
72
73       Tcl_ThreadId *idPtr (out)                     The referred storage will
74                                                     contain  the  id  of  the
75                                                     newly  created  thread as
76                                                     returned by the operating
77                                                     system.
78
79       Tcl_ThreadId id (in)                          Id  of  the thread waited
80                                                     upon.
81
82       Tcl_ThreadCreateProc threadProc (in)          This procedure  will  act
83                                                     as   the  main()  of  the
84                                                     newly created thread. The
85                                                     specified clientData will
86                                                     be its sole argument.
87
88       ClientData clientData (in)                    Arbitrary    information.
89                                                     Passed  as  sole argument
90                                                     to the threadProc.
91
92       int stackSize (in)                            The  size  of  the  stack
93                                                     given to the new thread.
94
95       int flags (in)                                Bitmask  containing flags
96                                                     allowing  the  caller  to
97                                                     modify  behaviour  of the
98                                                     new thread.
99
100       int *result (out)                             The referred  storage  is
101                                                     used  to  place  the exit
102                                                     code of the thread waited
103                                                     upon into it.
104_________________________________________________________________
105

INTRODUCTION

107       Beginning  with  the  8.1  release,  the Tcl core is thread safe, which
108       allows you to incorporate Tcl into multithreaded  applications  without
109       customizing  the  Tcl  core.  To enable Tcl multithreading support, you
110       must include the --enable-threads option to configure when you  config‐
111       ure and compile your Tcl core.
112
113       An  important constraint of the Tcl threads implementation is that only
114       the thread that created a Tcl interpreter can use that interpreter.  In
115       other  words, multiple threads can not access the same Tcl interpreter.
116       (However, a single thread can safely create  and  use  multiple  inter‐
117       preters.)
118

DESCRIPTION

120       Tcl  provides  Tcl_CreateThread  for  creating  threads. The caller can
121       determine the size of the stack given to the new thread and modify  the
122       behaviour     through     the     supplied     flags.     The     value
123       TCL_THREAD_STACK_DEFAULT for the stackSize indicates that  the  default
124       size  as  specified  by  the operating system is to be used for the new
125       thread. As for the flags, currently only the values  TCL_THREAD_NOFLAGS
126       and  TCL_THREAD_JOINABLE  are  defined.  The  first of them invokes the
127       default behaviour with no specialties. Using the second value marks the
128       new thread as joinable. This means that another thread can wait for the
129       such marked thread to exit and join it.
130
131       Restrictions: On some UNIX systems the pthread-library does not contain
132       the  functionality to specify the stack size of a thread. The specified
133       value for the stack size is ignored on  these  systems.   Windows  cur‐
134       rently  does not support joinable threads. This flag value is therefore
135       ignored on this platform.
136
137       Tcl provides the Tcl_ExitThread and  Tcl_FinalizeThread  functions  for
138       terminating  threads  and  invoking  optional per-thread exit handlers.
139       See the Tcl_Exit page for more information on these procedures.
140
141       The Tcl_JoinThread function is provided to allow threads to  wait  upon
142       the  exit  of  another  thread, which must have been marked as joinable
143       through usage of the TCL_THREAD_JOINABLE-flag during its  creation  via
144       Tcl_CreateThread.
145
146       Trying  to wait for the exit of a non-joinable thread or a thread which
147       is already waited upon will result in an error. Waiting for a  joinable
148       thread  which  already  exited  is possible, the system will retain the
149       necessary information until after the  call  to  Tcl_JoinThread.   This
150       means  that not calling Tcl_JoinThread for a joinable thread will cause
151       a memory leak.
152
153       The Tcl_GetThreadData call returns a pointer to a block of  thread-pri‐
154       vate  data.   Its argument is a key that is shared by all threads and a
155       size for the block of storage.  The storage is automatically  allocated
156       and  initialized  to  all zeros the first time each thread asks for it.
157       The storage is automatically deallocated by Tcl_FinalizeThread.
158
159   SYNCHRONIZATION AND COMMUNICATION
160       Tcl provides  Tcl_ThreadQueueEvent  and  Tcl_ThreadAlert  for  handling
161       event  queuing  in multithreaded applications.  See the Notifier manual
162       page for more information on these procedures.
163
164       A mutex is a lock that is used to serialize all threads through a piece
165       of  code  by  calling Tcl_MutexLock and Tcl_MutexUnlock.  If one thread
166       holds a mutex, any other thread calling Tcl_MutexLock will block  until
167       Tcl_MutexUnlock  is  called.  A mutex can be destroyed after its use by
168       calling Tcl_MutexFinalize.  The result of locking a  mutex  twice  from
169       the  same  thread  is undefined.  On some platforms it will result in a
170       deadlock.  The  Tcl_MutexLock,  Tcl_MutexUnlock  and  Tcl_MutexFinalize
171       procedures  are  defined  as empty macros if not compiling with threads
172       enabled.  For declaration of mutexes the TCL_DECLARE_MUTEX macro should
173       be  used.  This macro assures correct mutex handling even when the core
174       is compiled without threads enabled.
175
176       A condition variable is used as a signaling  mechanism:  a  thread  can
177       lock  a mutex and then wait on a condition variable with Tcl_Condition‐
178       Wait.  This atomically releases the mutex lock and blocks  the  waiting
179       thread  until  another thread calls Tcl_ConditionNotify.  The caller of
180       Tcl_ConditionNotify should have the associated mutex held by previously
181       calling  Tcl_MutexLock, but this is not enforced.  Notifying the condi‐
182       tion variable unblocks all threads waiting on the  condition  variable,
183       but  they  do not proceed until the mutex is released with Tcl_MutexUn‐
184       lock.  The implementation of Tcl_ConditionWait automatically locks  the
185       mutex before returning.
186
187       The caller of Tcl_ConditionWait should be prepared for spurious notifi‐
188       cations by calling Tcl_ConditionWait within a  while  loop  that  tests
189       some invariant.
190
191       A condition variable can be destroyed after its use by calling Tcl_Con‐
192       ditionFinalize.
193
194       The Tcl_ConditionNotify,  Tcl_ConditionWait  and  Tcl_ConditionFinalize
195       procedures  are  defined  as empty macros if not compiling with threads
196       enabled.
197
198   INITIALIZATION
199       All of these synchronization objects are self-initializing.   They  are
200       implemented as opaque pointers that should be NULL upon first use.  The
201       mutexes and condition variables are either cleaned up by  process  exit
202       handlers  (if  living that long) or explicitly by calls to Tcl_MutexFi‐
203       nalize or Tcl_ConditionFinalize.  Thread  local  storage  is  reclaimed
204       during Tcl_FinalizeThread.
205

SCRIPT-LEVEL ACCESS TO THREADS

207       Tcl provides no built-in commands for scripts to use to create, manage, │
208       or join threads, nor any script-level  access  to  mutex  or  condition │
209       variables.   It  provides  such  facilities  only via C interfaces, and │
210       leaves it up to packages to expose these matters to the  script  level. │
211       One such package is the Thread package.
212

SEE ALSO

214       Tcl_GetCurrentThread(3),  Tcl_ThreadQueueEvent(3),  Tcl_ThreadAlert(3),
215       Tcl_ExitThread(3),      Tcl_FinalizeThread(3),      Tcl_CreateThreadEx‐
216       itHandler(3), Tcl_DeleteThreadExitHandler(3), Thread
217

KEYWORDS

219       thread, mutex, condition variable, thread local storage
220
221
222
223Tcl                                   8.1                           Threads(3)
Impressum