605 lines
35 KiB
HTML
605 lines
35 KiB
HTML
|
|
<html><head>
|
|
<title>thread - Tcl Threading</title>
|
|
<style type="text/css"><!--
|
|
HTML {
|
|
background: #FFFFFF;
|
|
color: black;
|
|
}
|
|
BODY {
|
|
background: #FFFFFF;
|
|
color: black;
|
|
}
|
|
DIV.doctools {
|
|
margin-left: 10%;
|
|
margin-right: 10%;
|
|
}
|
|
DIV.doctools H1,DIV.doctools H2 {
|
|
margin-left: -5%;
|
|
}
|
|
H1, H2, H3, H4 {
|
|
margin-top: 1em;
|
|
font-family: sans-serif;
|
|
font-size: large;
|
|
color: #005A9C;
|
|
background: transparent;
|
|
text-align: left;
|
|
}
|
|
H1.doctools_title {
|
|
text-align: center;
|
|
}
|
|
UL,OL {
|
|
margin-right: 0em;
|
|
margin-top: 3pt;
|
|
margin-bottom: 3pt;
|
|
}
|
|
UL LI {
|
|
list-style: disc;
|
|
}
|
|
OL LI {
|
|
list-style: decimal;
|
|
}
|
|
DT {
|
|
padding-top: 1ex;
|
|
}
|
|
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
|
|
font: normal 12pt/14pt sans-serif;
|
|
list-style: none;
|
|
}
|
|
LI.doctools_section, LI.doctools_subsection {
|
|
list-style: none;
|
|
margin-left: 0em;
|
|
text-indent: 0em;
|
|
padding: 0em;
|
|
}
|
|
PRE {
|
|
display: block;
|
|
font-family: monospace;
|
|
white-space: pre;
|
|
margin: 0%;
|
|
padding-top: 0.5ex;
|
|
padding-bottom: 0.5ex;
|
|
padding-left: 1ex;
|
|
padding-right: 1ex;
|
|
width: 100%;
|
|
}
|
|
PRE.doctools_example {
|
|
color: black;
|
|
background: #f5dcb3;
|
|
border: 1px solid black;
|
|
}
|
|
UL.doctools_requirements LI, UL.doctools_syntax LI {
|
|
list-style: none;
|
|
margin-left: 0em;
|
|
text-indent: 0em;
|
|
padding: 0em;
|
|
}
|
|
DIV.doctools_synopsis {
|
|
color: black;
|
|
background: #80ffff;
|
|
border: 1px solid black;
|
|
font-family: serif;
|
|
margin-top: 1em;
|
|
margin-bottom: 1em;
|
|
}
|
|
UL.doctools_syntax {
|
|
margin-top: 1em;
|
|
border-top: 1px solid black;
|
|
}
|
|
UL.doctools_requirements {
|
|
margin-bottom: 1em;
|
|
border-bottom: 1px solid black;
|
|
}
|
|
--></style>
|
|
</head>
|
|
<! -- Generated from file '' by tcllib/doctools with format 'html'
|
|
-->
|
|
<! -- thread.n
|
|
-->
|
|
<body><div class="doctools">
|
|
<h1 class="doctools_title">thread(n) 2.8 "Tcl Threading"</h1>
|
|
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
|
|
<p>thread - Extension for script access to Tcl threading</p>
|
|
</div>
|
|
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
|
|
<ul class="doctools_toc">
|
|
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
|
|
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
|
|
<li class="doctools_section"><a href="#section1">Description</a></li>
|
|
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
|
|
<li class="doctools_section"><a href="#section3">DISCUSSION</a></li>
|
|
<li class="doctools_section"><a href="#see-also">See Also</a></li>
|
|
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
|
|
</ul>
|
|
</div>
|
|
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
|
|
<div class="doctools_synopsis">
|
|
<ul class="doctools_requirements">
|
|
<li>package require <b class="pkgname">Tcl 8.4</b></li>
|
|
<li>package require <b class="pkgname">Thread <span class="opt">?2.8?</span></b></li>
|
|
</ul>
|
|
<ul class="doctools_syntax">
|
|
<li><a href="#1"><b class="cmd">thread::create</b> <span class="opt">?-joinable?</span> <span class="opt">?-preserved?</span> <span class="opt">?script?</span></a></li>
|
|
<li><a href="#2"><b class="cmd">thread::preserve</b> <span class="opt">?id?</span></a></li>
|
|
<li><a href="#3"><b class="cmd">thread::release</b> <span class="opt">?-wait?</span> <span class="opt">?id?</span></a></li>
|
|
<li><a href="#4"><b class="cmd">thread::id</b></a></li>
|
|
<li><a href="#5"><b class="cmd">thread::errorproc</b> <span class="opt">?procname?</span></a></li>
|
|
<li><a href="#6"><b class="cmd">thread::cancel</b> <span class="opt">?-unwind?</span> <i class="arg">id</i> <span class="opt">?result?</span></a></li>
|
|
<li><a href="#7"><b class="cmd">thread::unwind</b></a></li>
|
|
<li><a href="#8"><b class="cmd">thread::exit</b> <span class="opt">?status?</span></a></li>
|
|
<li><a href="#9"><b class="cmd">thread::names</b></a></li>
|
|
<li><a href="#10"><b class="cmd">thread::exists</b> <i class="arg">id</i></a></li>
|
|
<li><a href="#11"><b class="cmd">thread::send</b> <span class="opt">?-async?</span> <span class="opt">?-head?</span> <i class="arg">id</i> <i class="arg">script</i> <span class="opt">?varname?</span></a></li>
|
|
<li><a href="#12"><b class="cmd">thread::broadcast</b> <i class="arg">script</i></a></li>
|
|
<li><a href="#13"><b class="cmd">thread::wait</b></a></li>
|
|
<li><a href="#14"><b class="cmd">thread::eval</b> <span class="opt">?-lock mutex?</span> <i class="arg">arg</i> <span class="opt">?arg ...?</span></a></li>
|
|
<li><a href="#15"><b class="cmd">thread::join</b> <i class="arg">id</i></a></li>
|
|
<li><a href="#16"><b class="cmd">thread::configure</b> <i class="arg">id</i> <span class="opt">?option?</span> <span class="opt">?value?</span> <span class="opt">?...?</span></a></li>
|
|
<li><a href="#17"><b class="cmd">thread::transfer</b> <i class="arg">id</i> <i class="arg">channel</i></a></li>
|
|
<li><a href="#18"><b class="cmd">thread::detach</b> <i class="arg">channel</i></a></li>
|
|
<li><a href="#19"><b class="cmd">thread::attach</b> <i class="arg">channel</i></a></li>
|
|
<li><a href="#20"><b class="cmd">thread::mutex</b></a></li>
|
|
<li><a href="#21"><b class="cmd">thread::mutex</b> <b class="method">create</b> <span class="opt">?-recursive?</span></a></li>
|
|
<li><a href="#22"><b class="cmd">thread::mutex</b> <b class="method">destroy</b> <i class="arg">mutex</i></a></li>
|
|
<li><a href="#23"><b class="cmd">thread::mutex</b> <b class="method">lock</b> <i class="arg">mutex</i></a></li>
|
|
<li><a href="#24"><b class="cmd">thread::mutex</b> <b class="method">unlock</b> <i class="arg">mutex</i></a></li>
|
|
<li><a href="#25"><b class="cmd">thread::rwmutex</b></a></li>
|
|
<li><a href="#26"><b class="cmd">thread::rwmutex</b> <b class="method">create</b></a></li>
|
|
<li><a href="#27"><b class="cmd">thread::rwmutex</b> <b class="method">destroy</b> <i class="arg">mutex</i></a></li>
|
|
<li><a href="#28"><b class="cmd">thread::rwmutex</b> <b class="method">rlock</b> <i class="arg">mutex</i></a></li>
|
|
<li><a href="#29"><b class="cmd">thread::rwmutex</b> <b class="method">wlock</b> <i class="arg">mutex</i></a></li>
|
|
<li><a href="#30"><b class="cmd">thread::rwmutex</b> <b class="method">unlock</b> <i class="arg">mutex</i></a></li>
|
|
<li><a href="#31"><b class="cmd">thread::cond</b></a></li>
|
|
<li><a href="#32"><b class="cmd">thread::cond</b> <b class="method">create</b></a></li>
|
|
<li><a href="#33"><b class="cmd">thread::cond</b> <b class="method">destroy</b> <i class="arg">cond</i></a></li>
|
|
<li><a href="#34"><b class="cmd">thread::cond</b> <b class="method">notify</b> <i class="arg">cond</i></a></li>
|
|
<li><a href="#35"><b class="cmd">thread::cond</b> <b class="method">wait</b> <i class="arg">cond</i> <i class="arg">mutex</i> <span class="opt">?ms?</span></a></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
|
|
<p>The <b class="package">thread</b> extension creates threads that contain Tcl
|
|
interpreters, and it lets you send scripts to those threads for
|
|
evaluation.
|
|
Additionaly, it provides script-level access to basic thread
|
|
synchronization primitives, like mutexes and condition variables.</p>
|
|
</div>
|
|
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
|
|
<p>This section describes commands for creating and destroying threads
|
|
and sending scripts to threads for evaluation.</p>
|
|
<dl class="doctools_definitions">
|
|
<dt><a name="1"><b class="cmd">thread::create</b> <span class="opt">?-joinable?</span> <span class="opt">?-preserved?</span> <span class="opt">?script?</span></a></dt>
|
|
<dd><p>This command creates a thread that contains a Tcl interpreter.
|
|
The Tcl interpreter either evaluates the optional <b class="option">script</b>, if
|
|
specified, or it waits in the event loop for scripts that arrive via
|
|
the <b class="cmd">thread::send</b> command. The result, if any, of the
|
|
optional <b class="option">script</b> is never returned to the caller.
|
|
The result of <b class="cmd">thread::create</b> is the ID of the thread. This is
|
|
the opaque handle which identifies the newly created thread for
|
|
all other package commands. The handle of the thread goes out of scope
|
|
automatically when thread is marked for exit
|
|
(see the <b class="cmd">thread::release</b> command below).</p>
|
|
<p>If the optional <b class="option">script</b> argument contains the <b class="cmd">thread::wait</b>
|
|
command the thread will enter into the event loop. If such command is not
|
|
found in the <b class="option">script</b> the thread will run the <b class="option">script</b> to
|
|
the end and exit. In that case, the handle may be safely ignored since it
|
|
refers to a thread which does not exists any more at the time when the
|
|
command returns.</p>
|
|
<p>Using flag <b class="option">-joinable</b> it is possible to create a joinable
|
|
thread, i.e. one upon whose exit can be waited upon by using
|
|
<b class="cmd">thread::join</b> command.
|
|
Note that failure to join a thread created with <b class="option">-joinable</b> flag
|
|
results in resource and memory leaks.</p>
|
|
<p>Threads created by the <b class="cmd">thread::create</b> cannot be destroyed
|
|
forcefully. Consequently, there is no corresponding thread destroy
|
|
command. A thread may only be released using the <b class="cmd">thread::release</b>
|
|
and if its internal reference count drops to zero, the thread is
|
|
marked for exit. This kicks the thread out of the event loop
|
|
servicing and the thread continues to execute commands passed in
|
|
the <b class="option">script</b> argument, following the <b class="cmd">thread::wait</b>
|
|
command. If this was the last command in the script, as usualy the
|
|
case, the thread will exit.</p>
|
|
<p>It is possible to create a situation in which it may be impossible
|
|
to terminate the thread, for example by putting some endless loop
|
|
after the <b class="cmd">thread::wait</b> or entering the event loop again by
|
|
doing an vwait-type of command. In such cases, the thread may never
|
|
exit. This is considered to be a bad practice and should be avoided
|
|
if possible. This is best illustrated by the example below:</p>
|
|
<pre class="doctools_example">
|
|
# You should never do ...
|
|
set tid [thread::create {
|
|
package require Http
|
|
thread::wait
|
|
vwait forever ; # <-- this!
|
|
}]
|
|
</pre>
|
|
<p>The thread created in the above example will never be able to exit.
|
|
After it has been released with the last matching <b class="cmd">thread::release</b>
|
|
call, the thread will jump out of the <b class="cmd">thread::wait</b> and continue
|
|
to execute commands following. It will enter <b class="cmd">vwait</b> command and
|
|
wait endlessly for events. There is no way one can terminate such thread,
|
|
so you wouldn't want to do this!</p>
|
|
<p>Each newly created has its internal reference counter set to 0 (zero),
|
|
i.e. it is unreserved. This counter gets incremented by a call to
|
|
<b class="cmd">thread::preserve</b> and decremented by a call to <b class="cmd">thread::release</b>
|
|
command. These two commands implement simple but effective thread
|
|
reservation system and offer predictable and controllable thread
|
|
termination capabilities. It is however possible to create initialy
|
|
preserved threads by using flag <b class="option">-preserved</b> of the
|
|
<b class="cmd">thread::create</b> command. Threads created with this flag have the
|
|
initial value of the reference counter of 1 (one), and are thus
|
|
initially marked reserved.</p></dd>
|
|
<dt><a name="2"><b class="cmd">thread::preserve</b> <span class="opt">?id?</span></a></dt>
|
|
<dd><p>This command increments the thread reference counter. Each call
|
|
to this command increments the reference counter by one (1).
|
|
Command returns the value of the reference counter after the increment.
|
|
If called with the optional thread <b class="option">id</b>, the command preserves
|
|
the given thread. Otherwise the current thread is preserved.</p>
|
|
<p>With reference counting, one can implement controlled access to a
|
|
shared Tcl thread. By incrementing the reference counter, the
|
|
caller signalizes that he/she wishes to use the thread for a longer
|
|
period of time. By decrementing the counter, caller signalizes that
|
|
he/she has finished using the thread.</p></dd>
|
|
<dt><a name="3"><b class="cmd">thread::release</b> <span class="opt">?-wait?</span> <span class="opt">?id?</span></a></dt>
|
|
<dd><p>This command decrements the thread reference counter. Each call to
|
|
this command decrements the reference counter by one (1).
|
|
If called with the optional thread <b class="option">id</b>, the command releases
|
|
the given thread. Otherwise, the current thread is released.
|
|
Command returns the value of the reference counter after the decrement.
|
|
When the reference counter reaches zero (0), the target thread is
|
|
marked for termination. You should not reference the thread after the
|
|
<b class="cmd">thread::release</b> command returns zero or negative integer.
|
|
The handle of the thread goes out of scope and should not be used any
|
|
more. Any following reference to the same thread handle will result
|
|
in Tcl error.</p>
|
|
<p>Optional flag <b class="option">-wait</b> instructs the caller thread to wait for
|
|
the target thread to exit, if the effect of the command would result
|
|
in termination of the target thread, i.e. if the return result would
|
|
be zero (0). Without the flag, the caller thread does not wait for
|
|
the target thread to exit. Care must be taken when using the
|
|
<b class="option">-wait</b>, since this may block the caller thread indefinitely.
|
|
This option has been implemented for some special uses of the extension
|
|
and is deprecated for regular use. Regular users should create joinable
|
|
threads by using the <b class="option">-joinable</b> option of the <b class="cmd">thread::create</b>
|
|
command and the <b class="cmd">thread::join</b> to wait for thread to exit.</p></dd>
|
|
<dt><a name="4"><b class="cmd">thread::id</b></a></dt>
|
|
<dd><p>This command returns the ID of the current thread.</p></dd>
|
|
<dt><a name="5"><b class="cmd">thread::errorproc</b> <span class="opt">?procname?</span></a></dt>
|
|
<dd><p>This command sets a handler for errors that occur in scripts sent
|
|
asynchronously, using the <b class="option">-async</b> flag of the
|
|
<b class="cmd">thread::send</b> command, to other threads. If no handler
|
|
is specified, the current handler is returned. The empty string
|
|
resets the handler to default (unspecified) value.
|
|
An uncaught error in a thread causes an error message to be sent
|
|
to the standard error channel. This default reporting scheme can
|
|
be changed by registering a procedure which is called to report
|
|
the error. The <i class="arg">procname</i> is called in the interpreter that
|
|
invoked the <b class="cmd">thread::errorproc</b> command. The <i class="arg">procname</i>
|
|
is called like this:</p>
|
|
<pre class="doctools_example">
|
|
myerrorproc thread_id errorInfo
|
|
</pre>
|
|
</dd>
|
|
<dt><a name="6"><b class="cmd">thread::cancel</b> <span class="opt">?-unwind?</span> <i class="arg">id</i> <span class="opt">?result?</span></a></dt>
|
|
<dd><p>This command requires Tcl version 8.6 or higher.</p>
|
|
<p>Cancels the script being evaluated in the thread given by the <i class="arg">id</i>
|
|
parameter. Without the <b class="option">-unwind</b> switch the evaluation stack for
|
|
the interpreter is unwound until an enclosing catch command is found or
|
|
there are no further invocations of the interpreter left on the call
|
|
stack. With the <b class="option">-unwind</b> switch the evaluation stack for the
|
|
interpreter is unwound without regard to any intervening catch command
|
|
until there are no further invocations of the interpreter left on the
|
|
call stack. If <i class="arg">result</i> is present, it will be used as the error
|
|
message string; otherwise, a default error message string will be used.</p></dd>
|
|
<dt><a name="7"><b class="cmd">thread::unwind</b></a></dt>
|
|
<dd><p>Use of this command is deprecated in favour of more advanced thread
|
|
reservation system implemented with <b class="cmd">thread::preserve</b> and
|
|
<b class="cmd">thread::release</b> commands. Support for <b class="cmd">thread::unwind</b>
|
|
command will dissapear in some future major release of the extension.</p>
|
|
<p>This command stops a prior <b class="cmd">thread::wait</b> command. Execution of
|
|
the script passed to newly created thread will continue from the
|
|
<b class="cmd">thread::wait</b> command. If <b class="cmd">thread::wait</b> was the last command
|
|
in the script, the thread will exit. The command returns empty result
|
|
but may trigger Tcl error with the message "target thread died" in some
|
|
situations.</p></dd>
|
|
<dt><a name="8"><b class="cmd">thread::exit</b> <span class="opt">?status?</span></a></dt>
|
|
<dd><p>Use of this command is deprecated in favour of more advanced thread
|
|
reservation system implemented with <b class="cmd">thread::preserve</b> and
|
|
<b class="cmd">thread::release</b> commands. Support for <b class="cmd">thread::exit</b>
|
|
command will dissapear in some future major release of the extension.</p>
|
|
<p>This command forces a thread stuck in the <b class="cmd">thread::wait</b> command to
|
|
unconditionaly exit. The thread's exit status defaults to 666 and can be
|
|
specified using the optional <i class="arg">status</i> argument. The execution of
|
|
<b class="cmd">thread::exit</b> command is guaranteed to leave the program memory in the
|
|
unconsistent state, produce memory leaks and otherwise affect other subsytem(s)
|
|
of the Tcl application in an unpredictable manner. The command returns empty
|
|
result but may trigger Tcl error with the message "target thread died" in some
|
|
situations.</p></dd>
|
|
<dt><a name="9"><b class="cmd">thread::names</b></a></dt>
|
|
<dd><p>This command returns a list of thread IDs. These are only for
|
|
threads that have been created via <b class="cmd">thread::create</b> command.
|
|
If your application creates other threads at the C level, they
|
|
are not reported by this command.</p></dd>
|
|
<dt><a name="10"><b class="cmd">thread::exists</b> <i class="arg">id</i></a></dt>
|
|
<dd><p>Returns true (1) if thread given by the <i class="arg">id</i> parameter exists,
|
|
false (0) otherwise. This applies only for threads that have
|
|
been created via <b class="cmd">thread::create</b> command.</p></dd>
|
|
<dt><a name="11"><b class="cmd">thread::send</b> <span class="opt">?-async?</span> <span class="opt">?-head?</span> <i class="arg">id</i> <i class="arg">script</i> <span class="opt">?varname?</span></a></dt>
|
|
<dd><p>This command passes a <i class="arg">script</i> to another thread and, optionally,
|
|
waits for the result. If the <b class="option">-async</b> flag is specified, the
|
|
command does not wait for the result and it returns empty string.
|
|
The target thread must enter it's event loop in order to receive
|
|
scripts sent via this command. This is done by default for threads
|
|
created without a startup script. Threads can enter the event loop
|
|
explicitly by calling <b class="cmd">thread::wait</b> or any other relevant Tcl/Tk
|
|
command, like <b class="cmd">update</b>, <b class="cmd">vwait</b>, etc.</p>
|
|
<p>Optional <b class="option">varname</b> specifies name of the variable to store
|
|
the result of the <i class="arg">script</i>. Without the <b class="option">-async</b> flag,
|
|
the command returns the evaluation code, similarily to the standard
|
|
Tcl <b class="cmd">catch</b> command. If, however, the <b class="option">-async</b> flag is
|
|
specified, the command returns immediately and caller can later
|
|
<b class="cmd">vwait</b> on <span class="opt">?varname?</span> to get the result of the passed <i class="arg">script</i></p>
|
|
<pre class="doctools_example">
|
|
set t1 [thread::create]
|
|
set t2 [thread::create]
|
|
thread::send -async $t1 "set a 1" result
|
|
thread::send -async $t2 "set b 2" result
|
|
for {set i 0} {$i < 2} {incr i} {
|
|
vwait result
|
|
}
|
|
</pre>
|
|
<p>In the above example, two threads were fed work and both of them were
|
|
instructed to signalize the same variable "result" in the calling thread.
|
|
The caller entered the event loop twice to get both results. Note,
|
|
however, that the order of the received results may vary, depending on
|
|
the current system load, type of work done, etc, etc.</p>
|
|
<p>Many threads can simultaneously send scripts to the target thread for
|
|
execution. All of them are entered into the event queue of the target
|
|
thread and executed on the FIFO basis, intermingled with optional other
|
|
events pending in the event queue of the target thread.
|
|
Using the optional <span class="opt">?-head?</span> switch, scripts posted to the thread's
|
|
event queue can be placed on the head, instead on the tail of the queue,
|
|
thus being executed in the LIFO fashion.</p></dd>
|
|
<dt><a name="12"><b class="cmd">thread::broadcast</b> <i class="arg">script</i></a></dt>
|
|
<dd><p>This command passes a <i class="arg">script</i> to all threads created by the
|
|
package for execution. It does not wait for response from any of
|
|
the threads.</p></dd>
|
|
<dt><a name="13"><b class="cmd">thread::wait</b></a></dt>
|
|
<dd><p>This enters the event loop so a thread can receive messages from
|
|
the <b class="cmd">thread::send</b> command. This command should only be used
|
|
within the script passed to the <b class="cmd">thread::create</b>. It should
|
|
be the very last command in the script. If this is not the case,
|
|
the exiting thread will continue executing the script lines past
|
|
the <b class="cmd">thread::wait</b> which is usually not what you want and/or
|
|
expect.</p>
|
|
<pre class="doctools_example">
|
|
set t1 [thread::create {
|
|
#
|
|
# Do some initialization work here
|
|
#
|
|
thread::wait ; # Enter the event loop
|
|
}]
|
|
</pre>
|
|
</dd>
|
|
<dt><a name="14"><b class="cmd">thread::eval</b> <span class="opt">?-lock mutex?</span> <i class="arg">arg</i> <span class="opt">?arg ...?</span></a></dt>
|
|
<dd><p>This command concatenates passed arguments and evaluates the
|
|
resulting script under the mutex protection. If no mutex is
|
|
specified by using the <span class="opt">?-lock mutex?</span> optional argument,
|
|
the internal static mutex is used.</p></dd>
|
|
<dt><a name="15"><b class="cmd">thread::join</b> <i class="arg">id</i></a></dt>
|
|
<dd><p>This command waits for the thread with ID <i class="arg">id</i> to exit and
|
|
then returns it's exit code. Errors will be returned for threads
|
|
which are not joinable or already waited upon by another thread.
|
|
Upon the join the handle of the thread has gone out of scope and
|
|
should not be used any more.</p></dd>
|
|
<dt><a name="16"><b class="cmd">thread::configure</b> <i class="arg">id</i> <span class="opt">?option?</span> <span class="opt">?value?</span> <span class="opt">?...?</span></a></dt>
|
|
<dd><p>This command configures various low-level aspects of the thread with
|
|
ID <i class="arg">id</i> in the similar way as the standard Tcl command
|
|
<b class="cmd">fconfigure</b> configures some Tcl channel options. Options currently
|
|
supported are: <b class="option">-eventmark</b> and <b class="option">-unwindonerror</b>.</p>
|
|
<p>The <b class="option">-eventmark</b> option, when set, limits the number of
|
|
asynchronously posted scripts to the thread event loop.
|
|
The <b class="cmd">thread::send -async</b> command will block until the number
|
|
of pending scripts in the event loop does not drop below the value
|
|
configured with <b class="option">-eventmark</b>. Default value for the
|
|
<b class="option">-eventmark</b> is 0 (zero) which effectively disables the checking,
|
|
i.e. allows for unlimited number of posted scripts.</p>
|
|
<p>The <b class="option">-unwindonerror</b> option, when set, causes the
|
|
target thread to unwind if the result of the script processing
|
|
resulted in error. Default value for the <b class="option">-unwindonerror</b>
|
|
is 0 (false), i.e. thread continues to process scripts after one
|
|
of the posted scripts fails.</p></dd>
|
|
<dt><a name="17"><b class="cmd">thread::transfer</b> <i class="arg">id</i> <i class="arg">channel</i></a></dt>
|
|
<dd><p>This moves the specified <i class="arg">channel</i> from the current thread
|
|
and interpreter to the main interpreter of the thread with the
|
|
given <i class="arg">id</i>. After the move the current interpreter has no
|
|
access to the channel any more, but the main interpreter of the
|
|
target thread will be able to use it from now on.
|
|
The command waits until the other thread has incorporated the
|
|
channel. Because of this it is possible to deadlock the
|
|
participating threads by commanding the other through a
|
|
synchronous <b class="cmd">thread::send</b> to transfer a channel to us.
|
|
This easily extends into longer loops of threads waiting for
|
|
each other. Other restrictions: the channel in question must
|
|
not be shared among multiple interpreters running in the
|
|
sending thread. This automatically excludes the special channels
|
|
for standard input, output and error.</p>
|
|
<p>Due to the internal Tcl core implementation and the restriction on
|
|
transferring shared channels, one has to take extra measures when
|
|
transferring socket channels created by accepting the connection
|
|
out of the <b class="cmd">socket</b> commands callback procedures:</p>
|
|
<pre class="doctools_example">
|
|
socket -server _Accept 2200
|
|
proc _Accept {s ipaddr port} {
|
|
after idle [list Accept $s $ipaddr $port]
|
|
}
|
|
proc Accept {s ipaddr port} {
|
|
set tid [thread::create]
|
|
thread::transfer $tid $s
|
|
}
|
|
</pre>
|
|
</dd>
|
|
<dt><a name="18"><b class="cmd">thread::detach</b> <i class="arg">channel</i></a></dt>
|
|
<dd><p>This detaches the specified <i class="arg">channel</i> from the current thread and
|
|
interpreter. After that, the current interpreter has no access to the
|
|
channel any more. The channel is in the parked state until some other
|
|
(or the same) thread attaches the channel again with <b class="cmd">thread::attach</b>.
|
|
Restrictions: same as for transferring shared channels with the
|
|
<b class="cmd">thread::transfer</b> command.</p></dd>
|
|
<dt><a name="19"><b class="cmd">thread::attach</b> <i class="arg">channel</i></a></dt>
|
|
<dd><p>This attaches the previously detached <i class="arg">channel</i> in the
|
|
current thread/interpreter. For already existing channels,
|
|
the command does nothing, i.e. it is not an error to attach the
|
|
same channel more than once. The first operation will actualy
|
|
perform the operation, while all subsequent operation will just
|
|
do nothing. Command throws error if the <i class="arg">channel</i> cannot be
|
|
found in the list of detached channels and/or in the current
|
|
interpreter.</p></dd>
|
|
<dt><a name="20"><b class="cmd">thread::mutex</b></a></dt>
|
|
<dd><p>Mutexes are most common thread synchronization primitives.
|
|
They are used to synchronize access from two or more threads to one or
|
|
more shared resources. This command provides script-level access to
|
|
exclusive and/or recursive mutexes. Exclusive mutexes can be locked
|
|
only once by one thread, while recursive mutexes can be locked many
|
|
times by the same thread. For recursive mutexes, number of lock and
|
|
unlock operations must match, otherwise, the mutex will never be
|
|
released, which would lead to various deadlock situations.</p>
|
|
<p>Care has to be taken when using mutexes in an multithreading program.
|
|
Improper use of mutexes may lead to various deadlock situations,
|
|
especially when using exclusive mutexes.</p>
|
|
<p>The <b class="cmd">thread::mutex</b> command supports following subcommands and options:</p>
|
|
<dl class="doctools_definitions">
|
|
<dt><a name="21"><b class="cmd">thread::mutex</b> <b class="method">create</b> <span class="opt">?-recursive?</span></a></dt>
|
|
<dd><p>Creates the mutex and returns it's opaque handle. This handle
|
|
should be used for any future reference to the newly created mutex.
|
|
If no optional <span class="opt">?-recursive?</span> argument was specified, the command
|
|
creates the exclusive mutex. With the <span class="opt">?-recursive?</span> argument,
|
|
the command creates a recursive mutex.</p></dd>
|
|
<dt><a name="22"><b class="cmd">thread::mutex</b> <b class="method">destroy</b> <i class="arg">mutex</i></a></dt>
|
|
<dd><p>Destroys the <i class="arg">mutex</i>. Mutex should be in unlocked state before
|
|
the destroy attempt. If the mutex is locked, the command will throw
|
|
Tcl error.</p></dd>
|
|
<dt><a name="23"><b class="cmd">thread::mutex</b> <b class="method">lock</b> <i class="arg">mutex</i></a></dt>
|
|
<dd><p>Locks the <i class="arg">mutex</i>. Locking the exclusive mutex may throw Tcl
|
|
error if on attempt to lock the same mutex twice from the same
|
|
thread. If your program logic forces you to lock the same mutex
|
|
twice or more from the same thread (this may happen in recursive
|
|
procedure invocations) you should consider using the recursive mutexes.</p></dd>
|
|
<dt><a name="24"><b class="cmd">thread::mutex</b> <b class="method">unlock</b> <i class="arg">mutex</i></a></dt>
|
|
<dd><p>Unlocks the <i class="arg">mutex</i> so some other thread may lock it again.
|
|
Attempt to unlock the already unlocked mutex will throw Tcl error.</p></dd>
|
|
</dl></dd>
|
|
<dt><a name="25"><b class="cmd">thread::rwmutex</b></a></dt>
|
|
<dd><p>This command creates many-readers/single-writer mutexes. Reader/writer
|
|
mutexes allow you to serialize access to a shared resource more optimally.
|
|
In situations where a shared resource gets mostly read and seldom modified,
|
|
you might gain some performace by using reader/writer mutexes instead of
|
|
exclusive or recursive mutexes.</p>
|
|
<p>For reading the resource, thread should obtain a read lock on the resource.
|
|
Read lock is non-exclusive, meaning that more than one thread can
|
|
obtain a read lock to the same resource, without waiting on other readers.
|
|
For changing the resource, however, a thread must obtain a exclusive
|
|
write lock. This lock effectively blocks all threads from gaining the
|
|
read-lock while the resource is been modified by the writer thread.
|
|
Only after the write lock has been released, the resource may be read-locked
|
|
again.</p>
|
|
<p>The <b class="cmd">thread::rwmutex</b> command supports following subcommands and options:</p>
|
|
<dl class="doctools_definitions">
|
|
<dt><a name="26"><b class="cmd">thread::rwmutex</b> <b class="method">create</b></a></dt>
|
|
<dd><p>Creates the reader/writer mutex and returns it's opaque handle.
|
|
This handle should be used for any future reference to the newly
|
|
created mutex.</p></dd>
|
|
<dt><a name="27"><b class="cmd">thread::rwmutex</b> <b class="method">destroy</b> <i class="arg">mutex</i></a></dt>
|
|
<dd><p>Destroys the reader/writer <i class="arg">mutex</i>. If the mutex is already locked,
|
|
attempt to destroy it will throw Tcl error.</p></dd>
|
|
<dt><a name="28"><b class="cmd">thread::rwmutex</b> <b class="method">rlock</b> <i class="arg">mutex</i></a></dt>
|
|
<dd><p>Locks the <i class="arg">mutex</i> for reading. More than one thread may read-lock
|
|
the same <i class="arg">mutex</i> at the same time.</p></dd>
|
|
<dt><a name="29"><b class="cmd">thread::rwmutex</b> <b class="method">wlock</b> <i class="arg">mutex</i></a></dt>
|
|
<dd><p>Locks the <i class="arg">mutex</i> for writing. Only one thread may write-lock
|
|
the same <i class="arg">mutex</i> at the same time. Attempt to write-lock same
|
|
<i class="arg">mutex</i> twice from the same thread will throw Tcl error.</p></dd>
|
|
<dt><a name="30"><b class="cmd">thread::rwmutex</b> <b class="method">unlock</b> <i class="arg">mutex</i></a></dt>
|
|
<dd><p>Unlocks the <i class="arg">mutex</i> so some other thread may lock it again.
|
|
Attempt to unlock already unlocked <i class="arg">mutex</i> will throw Tcl error.</p></dd>
|
|
</dl></dd>
|
|
<dt><a name="31"><b class="cmd">thread::cond</b></a></dt>
|
|
<dd><p>This command provides script-level access to condition variables.
|
|
A condition variable creates a safe environment for the program
|
|
to test some condition, sleep on it when false and be awakened
|
|
when it might have become true. A condition variable is always
|
|
used in the conjuction with an exclusive mutex. If you attempt
|
|
to use other type of mutex in conjuction with the condition
|
|
variable, a Tcl error will be thrown.</p>
|
|
<p>The command supports following subcommands and options:</p>
|
|
<dl class="doctools_definitions">
|
|
<dt><a name="32"><b class="cmd">thread::cond</b> <b class="method">create</b></a></dt>
|
|
<dd><p>Creates the condition variable and returns it's opaque handle.
|
|
This handle should be used for any future reference to newly
|
|
created condition variable.</p></dd>
|
|
<dt><a name="33"><b class="cmd">thread::cond</b> <b class="method">destroy</b> <i class="arg">cond</i></a></dt>
|
|
<dd><p>Destroys condition variable <i class="arg">cond</i>. Extreme care has to be taken
|
|
that nobody is using (i.e. waiting on) the condition variable,
|
|
otherwise unexpected errors may happen.</p></dd>
|
|
<dt><a name="34"><b class="cmd">thread::cond</b> <b class="method">notify</b> <i class="arg">cond</i></a></dt>
|
|
<dd><p>Wakes up all threads waiting on the condition variable <i class="arg">cond</i>.</p></dd>
|
|
<dt><a name="35"><b class="cmd">thread::cond</b> <b class="method">wait</b> <i class="arg">cond</i> <i class="arg">mutex</i> <span class="opt">?ms?</span></a></dt>
|
|
<dd><p>This command is used to suspend program execution until the condition
|
|
variable <i class="arg">cond</i> has been signalled or the optional timer has expired.
|
|
The exclusive <i class="arg">mutex</i> must be locked by the calling thread on entrance
|
|
to this command. If the mutex is not locked, Tcl error is thrown.
|
|
While waiting on the <i class="arg">cond</i>, the command releases <i class="arg">mutex</i>.
|
|
Before returning to the calling thread, the command re-acquires the
|
|
<i class="arg">mutex</i> again. Unlocking the <i class="arg">mutex</i> and waiting on the
|
|
condition variable <i class="arg">cond</i> is done atomically.</p>
|
|
<p>The <b class="option">ms</b> command option, if given, must be an integer specifying
|
|
time interval in milliseconds the command waits to be signalled.
|
|
Otherwise the command waits on condition notify forever.</p>
|
|
<p>In multithreading programs, there are many situations where a thread has
|
|
to wait for some event to happen until it is allowed to proceed.
|
|
This is usually accomplished by repeatedly testing a condition under the
|
|
mutex protection and waiting on the condition variable until the condition
|
|
evaluates to true:</p>
|
|
<pre class="doctools_example">
|
|
set mutex [thread::mutex create]
|
|
set cond [thread::cond create]
|
|
thread::mutex lock $mutex
|
|
while {<some_condition_is_true>} {
|
|
thread::cond wait $cond $mutex
|
|
}
|
|
# Do some work under mutex protection
|
|
thread::mutex unlock $mutex
|
|
</pre>
|
|
<p>Repeated testing of the condition is needed since the condition variable
|
|
may get signalled without the condition being actually changed (spurious
|
|
thread wake-ups, for example).</p></dd>
|
|
</dl></dd>
|
|
</dl>
|
|
</div>
|
|
<div id="section3" class="doctools_section"><h2><a name="section3">DISCUSSION</a></h2>
|
|
<p>The fundamental threading model in Tcl is that there can be one or
|
|
more Tcl interpreters per thread, but each Tcl interpreter should
|
|
only be used by a single thread which created it.
|
|
A "shared memory" abstraction is awkward to provide in Tcl because
|
|
Tcl makes assumptions about variable and data ownership. Therefore
|
|
this extension supports a simple form of threading where the main
|
|
thread can manage several background, or "worker" threads.
|
|
For example, an event-driven server can pass requests to worker
|
|
threads, and then await responses from worker threads or new client
|
|
requests. Everything goes through the common Tcl event loop, so
|
|
message passing between threads works naturally with event-driven I/O,
|
|
<b class="cmd">vwait</b> on variables, and so forth. For the transfer of bulk
|
|
information it is possible to move channels between the threads.</p>
|
|
<p>For advanced multithreading scripts, script-level access to two
|
|
basic synchronization primitives, mutex and condition variables,
|
|
is also supported.</p>
|
|
</div>
|
|
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
|
|
<p><a href="http://www.tcl.tk/doc/howto/thread_model.html">http://www.tcl.tk/doc/howto/thread_model.html</a>, tpool, tsv, ttrace</p>
|
|
</div>
|
|
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
|
|
<p>events, message passing, mutex, synchronization, thread</p>
|
|
</div>
|
|
</div></body></html>
|
|
|