2 '\" Copyright (c) 1999 Scriptics Corporation
3 '\" Copyright (c) 1998 Sun Microsystems, Inc.
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8 .TH Threads 3 "8.1" Tcl "Tcl Library Procedures"
9 .\" The -*- nroff -*- definitions below are for supplemental macros used
10 .\" in Tcl/Tk manual entries.
12 .\" .AP type name in/out ?indent?
13 .\" Start paragraph describing an argument to a library procedure.
14 .\" type is type of argument (int, etc.), in/out is either "in", "out",
15 .\" or "in/out" to describe whether procedure reads or modifies arg,
16 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
17 .\" needed; use .AS below instead)
20 .\" Give maximum sizes of arguments for setting tab stops. Type and
21 .\" name are examples of largest possible arguments that will be passed
22 .\" to .AP later. If args are omitted, default tab stops are used.
25 .\" Start box enclosure. From here until next .BE, everything will be
26 .\" enclosed in one large box.
29 .\" End of box enclosure.
32 .\" Begin code excerpt.
37 .\" .VS ?version? ?br?
38 .\" Begin vertical sidebar, for use in marking newly-changed parts
39 .\" of man pages. The first argument is ignored and used for recording
40 .\" the version when the .VS was added, so that the sidebars can be
41 .\" found and removed when they reach a certain age. If another argument
42 .\" is present, then a line break is forced before starting the sidebar.
45 .\" End of vertical sidebar.
48 .\" Begin an indented unfilled display.
51 .\" End of indented unfilled display.
54 .\" Start of list of standard options for a Tk widget. The manpage
55 .\" argument defines where to look up the standard options; if
56 .\" omitted, defaults to "options". The options follow on successive
57 .\" lines, in three columns separated by tabs.
60 .\" End of list of standard options for a Tk widget.
62 .\" .OP cmdName dbName dbClass
63 .\" Start of description of a specific option. cmdName gives the
64 .\" option's name as specified in the class command, dbName gives
65 .\" the option's name in the option database, and dbClass gives
66 .\" the option's class in the option database.
69 .\" Print arg1 underlined, then print arg2 normally.
72 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
75 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
76 .\" (for trailing punctuation) and then a closing parenthesis.
78 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
82 .\" # Start an argument description
86 . ie !"\\$2"" .TP \\n()Cu
91 \&\\$1 \\fI\\$2\\fP (\\$3)
104 .\" # define tabbing values for .AP
107 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
110 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
111 .nr )C \\n()Bu+\\w'(in/out)'u+2n
113 .AS Tcl_Interp Tcl_CreateInterp in/out
114 .\" # BS - start boxed text
115 .\" # ^y = starting y location
123 .if n \l'\\n(.lu\(ul'
126 .\" # BE - end boxed text (draw box now)
131 .ie n \l'\\n(^lu\(ul'
133 .\" Draw four-sided box normally, but don't draw top of
134 .\" box if the box started on an earlier page.
136 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
139 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
146 .\" # VS - start vertical sidebar
147 .\" # ^Y = starting y location
148 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
152 .ie n 'mc \s12\(br\s0
155 .\" # VE - end of vertical sidebar
163 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
170 .\" # Special macro to handle page bottom: finish off current
171 .\" # box/sidebar if in box/sidebar mode, then invoked standard
172 .\" # page bottom macro.
179 .\" Draw three-sided box if this is the box's first page,
180 .\" draw two sides but no top otherwise.
181 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
182 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
185 .nr ^x \\n(^tu+1v-\\n(^Yu
186 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
199 .\" # DS - begin display
205 .\" # DE - end display
211 .\" # SO - start of list of standard options
213 'ie '\\$1'' .ds So \\fBoptions\\fR
214 'el .ds So \\fB\\$1\\fR
215 .SH "STANDARD OPTIONS"
221 .\" # SE - end of list of standard options
226 See the \\*(So manual entry for details on the standard options.
228 .\" # OP - start of full description for a single option
233 Command-Line Name: \\fB\\$1\\fR
234 Database Name: \\fB\\$2\\fR
235 Database Class: \\fB\\$3\\fR
239 .\" # CS - begin code excerpt
245 .\" # CE - end code excerpt
250 .\" # UL - underline word
254 .\" # QW - apply quotation marks to word
256 .ie '\\*(lq'"' ``\\$1''\\$2
257 .\"" fix emacs highlighting
258 .el \\*(lq\\$1\\*(rq\\$2
260 .\" # PQ - apply parens and quotation marks to word
262 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
263 .\"" fix emacs highlighting
264 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
266 .\" # QR - quoted range
268 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
269 .\"" fix emacs highlighting
270 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
272 .\" # MT - "empty" string
278 Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize, Tcl_CreateThread, Tcl_JoinThread \- Tcl thread support
281 \fB#include <tcl.h>\fR
284 \fBTcl_ConditionNotify\fR(\fIcondPtr\fR)
287 \fBTcl_ConditionWait\fR(\fIcondPtr, mutexPtr, timePtr\fR)
290 \fBTcl_ConditionFinalize\fR(\fIcondPtr\fR)
293 \fBTcl_GetThreadData\fR(\fIkeyPtr, size\fR)
296 \fBTcl_MutexLock\fR(\fImutexPtr\fR)
299 \fBTcl_MutexUnlock\fR(\fImutexPtr\fR)
302 \fBTcl_MutexFinalize\fR(\fImutexPtr\fR)
305 \fBTcl_CreateThread\fR(\fIidPtr, proc, clientData, stackSize, flags\fR)
308 \fBTcl_JoinThread\fR(\fIid, result\fR)
310 .AS Tcl_CreateThreadProc proc out
311 .AP Tcl_Condition *condPtr in
312 A condition variable, which must be associated with a mutex lock.
313 .AP Tcl_Mutex *mutexPtr in
315 .AP "const Tcl_Time" *timePtr in
316 A time limit on the condition wait. NULL to wait forever.
317 Note that a polling value of 0 seconds does not make much sense.
318 .AP Tcl_ThreadDataKey *keyPtr in
319 This identifies a block of thread local storage. The key should be
320 static and process-wide, yet each thread will end up associating
321 a different block of storage with this key.
323 The size of the thread local storage block. This amount of data
324 is allocated and initialized to zero the first time each thread
325 calls \fBTcl_GetThreadData\fR.
326 .AP Tcl_ThreadId *idPtr out
327 The referred storage will contain the id of the newly created thread as
328 returned by the operating system.
329 .AP Tcl_ThreadId id in
330 Id of the thread waited upon.
331 .AP Tcl_ThreadCreateProc *proc in
332 This procedure will act as the \fBmain()\fR of the newly created
333 thread. The specified \fIclientData\fR will be its sole argument.
334 .AP ClientData clientData in
335 Arbitrary information. Passed as sole argument to the \fIproc\fR.
337 The size of the stack given to the new thread.
339 Bitmask containing flags allowing the caller to modify behavior of
342 The referred storage is used to place the exit code of the thread
346 Beginning with the 8.1 release, the Tcl core is thread safe, which
347 allows you to incorporate Tcl into multithreaded applications without
348 customizing the Tcl core. To enable Tcl multithreading support,
349 you must include the \fB\-\|\-enable-threads\fR option to \fBconfigure\fR
350 when you configure and compile your Tcl core.
352 An important constraint of the Tcl threads implementation is that
353 \fIonly the thread that created a Tcl interpreter can use that
354 interpreter\fR. In other words, multiple threads can not access
355 the same Tcl interpreter. (However, a single thread can safely create
356 and use multiple interpreters.)
358 Tcl provides \fBTcl_CreateThread\fR for creating threads. The
359 caller can determine the size of the stack given to the new thread and
360 modify the behavior through the supplied \fIflags\fR. The value
361 \fBTCL_THREAD_STACK_DEFAULT\fR for the \fIstackSize\fR indicates that
362 the default size as specified by the operating system is to be used
363 for the new thread. As for the flags, currently only the values
364 \fBTCL_THREAD_NOFLAGS\fR and \fBTCL_THREAD_JOINABLE\fR are defined. The
365 first of them invokes the default behavior with no special settings.
366 Using the second value marks the new thread as \fIjoinable\fR. This
367 means that another thread can wait for the such marked thread to exit
370 Restrictions: On some UNIX systems the pthread-library does not
371 contain the functionality to specify the stack size of a thread. The
372 specified value for the stack size is ignored on these systems.
373 Windows currently does not support joinable threads. This
374 flag value is therefore ignored on this platform.
376 Tcl provides the \fBTcl_ExitThread\fR and \fBTcl_FinalizeThread\fR functions
377 for terminating threads and invoking optional per-thread exit
378 handlers. See the \fBTcl_Exit\fR page for more information on these
381 The \fBTcl_JoinThread\fR function is provided to allow threads to wait
382 upon the exit of another thread, which must have been marked as
383 joinable through usage of the \fBTCL_THREAD_JOINABLE\fR-flag during
384 its creation via \fBTcl_CreateThread\fR.
386 Trying to wait for the exit of a non-joinable thread or a thread which
387 is already waited upon will result in an error. Waiting for a joinable
388 thread which already exited is possible, the system will retain the
389 necessary information until after the call to \fBTcl_JoinThread\fR.
390 This means that not calling \fBTcl_JoinThread\fR for a joinable thread
391 will cause a memory leak.
393 The \fBTcl_GetThreadData\fR call returns a pointer to a block of
394 thread-private data. Its argument is a key that is shared by all threads
395 and a size for the block of storage. The storage is automatically
396 allocated and initialized to all zeros the first time each thread asks for it.
397 The storage is automatically deallocated by \fBTcl_FinalizeThread\fR.
398 .SS "SYNCHRONIZATION AND COMMUNICATION"
399 Tcl provides \fBTcl_ThreadQueueEvent\fR and \fBTcl_ThreadAlert\fR
400 for handling event queuing in multithreaded applications. See
401 the \fBNotifier\fR manual page for more information on these procedures.
403 A mutex is a lock that is used to serialize all threads through a piece
404 of code by calling \fBTcl_MutexLock\fR and \fBTcl_MutexUnlock\fR.
405 If one thread holds a mutex, any other thread calling \fBTcl_MutexLock\fR will
406 block until \fBTcl_MutexUnlock\fR is called.
407 A mutex can be destroyed after its use by calling \fBTcl_MutexFinalize\fR.
408 The result of locking a mutex twice from the same thread is undefined.
409 On some platforms it will result in a deadlock.
410 The \fBTcl_MutexLock\fR, \fBTcl_MutexUnlock\fR and \fBTcl_MutexFinalize\fR
411 procedures are defined as empty macros if not compiling with threads enabled.
412 For declaration of mutexes the \fBTCL_DECLARE_MUTEX\fR macro should be used.
413 This macro assures correct mutex handling even when the core is compiled
414 without threads enabled.
416 A condition variable is used as a signaling mechanism:
417 a thread can lock a mutex and then wait on a condition variable
418 with \fBTcl_ConditionWait\fR. This atomically releases the mutex lock
419 and blocks the waiting thread until another thread calls
420 \fBTcl_ConditionNotify\fR. The caller of \fBTcl_ConditionNotify\fR should
421 have the associated mutex held by previously calling \fBTcl_MutexLock\fR,
422 but this is not enforced. Notifying the
423 condition variable unblocks all threads waiting on the condition variable,
424 but they do not proceed until the mutex is released with \fBTcl_MutexUnlock\fR.
425 The implementation of \fBTcl_ConditionWait\fR automatically locks
426 the mutex before returning.
428 The caller of \fBTcl_ConditionWait\fR should be prepared for spurious
429 notifications by calling \fBTcl_ConditionWait\fR within a while loop
430 that tests some invariant.
432 A condition variable can be destroyed after its use by calling
433 \fBTcl_ConditionFinalize\fR.
435 The \fBTcl_ConditionNotify\fR, \fBTcl_ConditionWait\fR and
436 \fBTcl_ConditionFinalize\fR procedures are defined as empty macros if
437 not compiling with threads enabled.
440 All of these synchronization objects are self-initializing.
441 They are implemented as opaque pointers that should be NULL
443 The mutexes and condition variables are
444 either cleaned up by process exit handlers (if living that long) or
445 explicitly by calls to \fBTcl_MutexFinalize\fR or
446 \fBTcl_ConditionFinalize\fR.
447 Thread local storage is reclaimed during \fBTcl_FinalizeThread\fR.
448 .SH "SCRIPT-LEVEL ACCESS TO THREADS"
450 Tcl provides no built-in commands for scripts to use to create,
451 manage, or join threads, nor any script-level access to mutex or
452 condition variables. It provides such facilities only via C
453 interfaces, and leaves it up to packages to expose these matters to
454 the script level. One such package is the \fBThread\fR package.
457 To create a thread with portable code, its implementation function should be
461 static \fBTcl_ThreadCreateProc\fR MyThreadImplFunc;
464 It should then be defined like this example, which just counts up to a given
465 value and then finishes.
468 static \fBTcl_ThreadCreateType\fR
470 ClientData clientData)
472 int i, limit = (int) clientData;
473 for (i=0 ; i<limit ; i++) {
474 /* doing nothing at all here */
476 \fBTCL_THREAD_CREATE_RETURN\fR;
480 To create the above thread, make it execute, and wait for it to finish, we
484 int limit = 1000000000;
485 ClientData limitData = (void*)((intptr_t) limit);
486 Tcl_ThreadId id; \fI/* holds identity of thread created */\fR
489 if (\fBTcl_CreateThread\fR(&id, MyThreadImplFunc, limitData,
490 \fBTCL_THREAD_STACK_DEFAULT\fR,
491 \fBTCL_THREAD_JOINABLE\fR) != TCL_OK) {
492 \fI/* Thread did not create correctly */\fR
495 \fI/* Do something else for a while here */\fR
496 if (\fBTcl_JoinThread\fR(id, &result) != TCL_OK) {
497 \fI/* Thread did not finish properly */\fR
500 \fI/* All cleaned up nicely */\fR
503 Tcl_GetCurrentThread(3), Tcl_ThreadQueueEvent(3), Tcl_ThreadAlert(3),
504 Tcl_ExitThread(3), Tcl_FinalizeThread(3), Tcl_CreateThreadExitHandler(3),
505 Tcl_DeleteThreadExitHandler(3), Thread
507 thread, mutex, condition variable, thread local storage
OSDN Git Service
