thread(n) thread(n)
____________________________________________________________________________________________________________
NAME
thread - Extension for script access to Tcl threading
SYNOPSIS
package require Tcl 8.3
package require Thread ?2.6?
thread::create ?-joinable? ?-preserved? ?script?
thread::preserve ?id?
thread::release ?-wait? ?id?
thread::id
thread::errorproc ?procname?
thread::unwind
thread::exit
thread::names
thread::exists id
thread::send ?-async? id script ?varname?
thread::broadcast id script
thread::wait
thread::eval ?-lock mutex? arg ?arg ...?
thread::join id
thread::configure id ?option? ?value? ?...?
thread::transfer id channel
thread::detach channel
thread::attach channel
thread::mutex
thread::mutex create ?-recursive?
thread::mutex destroy mutex
thread::mutex lock mutex
thread::mutex unlock mutex
thread::rwmutex
thread::rwmutex create
thread::rwmutex destroy mutex
thread::rwmutex rlock mutex
thread::rwmutex wlock mutex
thread::rwmutex unlock mutex
thread::cond
thread::cond create
thread::cond destroy cond
thread::cond notify cond
thread::cond wait cond mutex ?ms?
____________________________________________________________________________________________________________
DESCRIPTION
The thread 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 synchro-nization synchronization
nization primitives, like mutexes and condition variables.
COMMANDS
This section describes commands for creating and destroying threads and sending scripts to threads
for evaluation.
thread::create ?-joinable? ?-preserved? ?script?
This command creates a thread that contains a Tcl interpreter. The Tcl interpreter either
evaluates the optional script, if specified, or it waits in the event loop for scripts that
arrive via the thread::send command. The result, if any, of the optional script is never
returned to the caller. The result of thread::create is the ID of the thread. This is the
small integer 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 thread::release command below).
If the optional script argument contains the thread::wait command the thread will enter into
the event loop. If such command is not found in the script the thread will run the script 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.
Using flag -joinable it is possible to create a joinable thread, i.e. one upon whose exit can
be waited upon by using thread::join command. Note that only Tcl8.4+ core supports joinable
threads. Note also that failure to join a thread created with -joinable flag results in
resource and memory leaks.
Threads created by the thread::create cannot be destroyed forcefully. Consequently, there is
no corresponding thread destroy command. A thread may only be released using the
thread::release 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 exe-cute execute
cute commands passed in the script argument, following the thread::wait command. If this was
the last command in the script, as usualy the case, the thread will exit.
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 thread::wait 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:
# You should never do ...
set tid [thread::create {
package require Http
thread::wait
vwait forever ; # <-- this!
}]
The thread created in the above example will never be able to exit. After it has been
released with the last matching thread::release call, the thread will jump out of the
thread::wait and continue to execute commands following. It will enter vwait command and wait
endlessly for events. There is no way one can terminate such thread, so you wouldn't want to
do this!
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 thread::preserve and decremented by a call to
thread::release 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 -preserved of the thread::create
command. Threads created with this flag have the initial value of the reference counter of 1
(one), and are thus initially marked reserved.
thread::preserve ?id?
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 id, the command preserves the given thread.
Otherwise the current thread is preserved.
With reference counting, one can implement controlled access to a shared Tcl thread. By incre-
menting 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 fin-ished finished
ished using the thread.
thread::release ?-wait? ?id?
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 id, 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 tar-get target
get thread is marked for termination. You should not reference the thread after the
thread::release 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.
Optional flag -wait 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 -wait, since this may block the caller
thread indefinitely. This option has been implemented for users of Tcl 8.3 version only.
Users of Tcl 8.4 or later should create joinable threads, by using the -joinable option of the
thread::create command and the thread::join to wait for thread exit.
thread::id
This command returns the ID of the current thread.
thread::errorproc ?procname?
This command sets a handler for errors that occur in scripts sent asynchronously, using the
-async flag of the thread::send 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 procname is called in the interpreter that invoked the
thread::errorproc command. The procname is called like this:
myerrorproc thread_id errorInfo
thread::unwind
Use of this command is deprecated in favour of more advanced thread reservation system imple-mented implemented
mented with thread::preserve and thread::release commands. Support for thread::unwind command
will dissapear in some future major release of the extension.
This command stops a prior thread::wait command. Execution of the script passed to newly cre-ated created
ated thread will continue from the thread::wait command. If thread::wait 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.
thread::exit
Use of this command is deprecated in favour of more advanced thread reservation system imple-mented implemented
mented with thread::preserve and thread::release commands. Support for thread::exit command
will dissapear in some future major release of the extension.
This command forces a thread stuck in the thread::wait command to unconditionaly exit. The
execution of thread::exit command is guaranteed to leave the program memory in the unconsis-tent unconsistent
tent 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.
thread::names
This command returns a list of thread IDs. These are only for threads that have been created
via thread::create command. If your application creates other threads at the C level, they
are not reported by this command.
thread::exists id
Returns true (1) if thread given by the id parameter exists, false (0) otherwise. This applies
only for threads that have been created via thread::create command.
thread::send ?-async? id script ?varname?
This command passes a script to another thread and, optionally, waits for the result. If the
-async 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 thread::wait or any other relevant Tcl/Tk com-mand, command,
mand, like update, vwait, etc.
Optional varname specifies name of the variable to store the result of the script. Without the
-async flag, the command returns the evaluation code, similarily to the standard Tcl catch
command. If, however, the -async flag is specified, the command returns immediately and caller
can later vwait on ?varname? to get the result of the passed script
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
}
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.
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, inter-
mingled with optional other events pending in the event queue of the target thread.
thread::broadcast id script
This command passes a script to all threads created by the package for execution. It does not
wait for response from any of the threads.
thread::wait
This enters the event loop so a thread can receive messages from the thread::send command.
This command should only be used within the script passed to the thread::create. 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 pass the thread::wait which is usually not what you want and/or
expect.
set t1 [thread::create {
#
# Do some initialization work here
#
thread::wait ; # Enter the event loop
}]
thread::eval ?-lock mutex? arg ?arg ...?
This command concatenates passed arguments and evaluates the resulting script under the mutex
protection. If no mutex is specified by using the ?-lock mutex? optional argument, the inter-nal internal
nal static mutex is used.
thread::join id
This command waits for the thread with ID id 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.
NOTE: This command is available only when loaded into the Tcl8.4+ shell.
thread::configure id ?option? ?value? ?...?
This command configures various low-level aspects of the thread with ID id in the similar way
as the standard Tcl command fconfigure configures some Tcl channel options. Options currently
supported are: -eventmark and -unwindonerror.
The -eventmark option, when set, limits the number of asynchronously posted scripts to the
thread event loop. The thread::send -async command will block until the number of pending
scripts in the event loop does not drop below the value configured with -eventmark. Default
value for the -eventmark is 0 (zero) which effectively disables the checking, i.e. allows for
unlimited number of posted scripts.
The -unwindonerror option, when set, causes the target thread to unwind if the result of the
script processing resulted in error. Default value for the -unwindonerror is 0 (false), i.e.
thread continues to process scripts after one of the posted scripts fails.
thread::transfer id channel
This moves the specified channel from the current thread and interpreter to the main inter-preter interpreter
preter of the thread with the given id. 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 thread::send 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.
Due to the internal Tcl core implementation and the restriction on transferring shared chan-nels, channels,
nels, one has to take extra measures when transferring socket channels created by accepting
the connection out of the socket commands callback procedures:
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
}
NOTE: this command is available only when loaded into the Tcl8.4+ shell.
thread::detach channel
This detaches the specified channel 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 thread::attach.
Restrictions: same as for transferring shared channels with the thread::transfer command.
NOTE: this command is available only when loaded into the Tcl8.4+ shell.
thread::attach channel
This attaches the previously detached channel in the current thread/interpreter. For already
existing channels, the command does nothing, i.e. it is not an error to attach the same chan-nel channel
nel more than once. The first operation will actualy perform the operation, while all subse-quent subsequent
quent operation will just do nothing. Command throws error if the channel cannot be found in
the list of detached channels and/or in the current interpreter.
NOTE: this command is available only when loaded into the Tcl8.4+ shell.
thread::mutex
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 scriptlevel
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 recur-sive recursive
sive mutexes, number of lock and unlock operations must match, otherwise, the mutex will never
be released, which would lead to various deadlock situations.
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.
The thread::mutex command supports following subcommands and options:
thread::mutex create ?-recursive?
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 ?-recursive? argument was
specified, the command creates the exclusive mutex. With the ?-recursive? argument, the
command creates a recursive mutex.
thread::mutex destroy mutex
Destroys the mutex. Mutex should be in unlocked state before the destroy attempt. If
the mutex is locked, the command will throw Tcl error.
thread::mutex lock mutex
Locks the mutex. 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.
thread::mutex unlock mutex
Unlocks the mutex so some other thread may lock it again. Attempt to unlock the
already unlocked mutex will throw Tcl error.
thread::rwmutex
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.
For reading the resource, thread should obtain a read lock on the resource. Read lock is non-exclusive, nonexclusive,
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.
The thread::rwmutex command supports following subcommands and options:
thread::rwmutex create
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.
thread::rwmutex destroy mutex
Destroys the reader/writer mutex. If the mutex is already locked, attempt to destroy it
will throw Tcl error.
thread::rwmutex rlock mutex
Locks the mutex for reading. More than one thread may read-lock the same mutex at the
same time.
thread::rwmutex wlock mutex
Locks the mutex for writing. Only one thread may write-lock the same mutex at the same
time. Attempt to write-lock same mutex twice from the same thread will throw Tcl error.
thread::rwmutex unlock mutex
Unlocks the mutex so some other thread may lock it again. Attempt to unlock already
unlocked mutex will throw Tcl error.
thread::cond
This command provides script-level access to condition variables. A condition variable cre-ates creates
ates 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 con-dition condition
dition variable, a Tcl error will be thrown.
The command supports following subcommands and options:
thread::cond create
Creates the condition variable and returns it's opaque handle. This handle should be
used for any future reference to newly created condition variable.
thread::cond destroy cond
Destroys condition variable cond. Extreme care has to be taken that nobody is using
(i.e. waiting on) the condition variable, otherwise unexpected errors may happen.
thread::cond notify cond
Wakes up all threads waiting on the condition variable cond.
thread::cond wait cond mutex ?ms?
This command is used to suspend program execution until the condition variable cond has
been signalled or the optional timer has expired. The exclusive mutex 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 cond, the command releases mutex. Before
returning to the calling thread, the command re-acquires the mutex again. Unlocking the
mutex and waiting on the condition variable cond is done atomically.
The ms command option, if given, must be an integer specifying time interval in mil-liseconds milliseconds
liseconds the command waits to be signalled. Otherwise the command waits on condition
notify forever.
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:
set mutex [thread::mutex create]
set cond [thread::cond create]
thread::mutex lock
while {<some_condition_is_true>} {
thread::cond wait $cond $mutex
}
# Do some work under mutex protection
thread::mutex unlock
Repeated testing of the condition is needed since the condition variable may get sig-nalled signalled
nalled without the condition being actually changed (spurious thread wake-ups, for
example).
DISCUSSION
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 owner-ship. ownership.
ship. 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 eventdriven
driven I/O, vwait on variables, and so forth. For the transfer of bulk information it is possible to
move channels between the threads.
For advanced multithreading scripts, script-level access to two basic synchronization primitives,
mutex and condition variables, is also supported.
SEE ALSO
http://www.tcl.tk/doc/howto/thread_model.html tpool, tsv, ttrace
KEYWORDS
events, message passing, mutex, synchronization, thread
Tcl Threading 2.6 thread(n)
|