The Thread Package Commands

The commands of the Thread extension are grouped into three separate namespaces, based on their functionality. This section summarizes the commands found in each namespace.

The thread Namespace

The thread namespace contains all of the commands for creating and managing threads, including inter-thread messaging, mutexes, and condition variables. Table 21-1 describes all of the commands contained in the thread namespace.

Table 21-1. The commands of the thread namespace

thread::attach channel	Attaches the previously detached channel into current interpreter of the current thread.
thread::cond create	Returns a token for a newly created condition variable.
thread::cond destroy cond	Destroys the specified condition variable.
thread::cond notify cond	Wakes up all threads waiting on the specified condition variable.
thread::cond wait cond mutex ?ms?	Blocks until the specified condition variable is signaled by another thread with thread::cond notify, or until the optional timeout in milliseconds specified by ms expires. The mutex must be locked by the calling thread before calling thread::cond wait. While waiting on the cond, the command releases mutex. Before returning to the calling thread, the command re-acquires mutex again.
thread::configure id ?option?value? ?option value...?	Queries or sets thread configuration options, as described in Table 21-2.
thread::create ?-joinable? ?-preserved? ?script?	Creates a thread, returning the thread's ID. The -joinable flag allows another thread to wait for termination of this thread with thread::join. The -preserved flag sets the thread's initial reference count to 1, rather than the default of 0. (See thread::preserve and thread::release.) If provided, the thread executes the script, then exits; otherwise, it enters an events loop to wait for messages.
thread::detach channel	Detaches the specified channel from the current thread so that it no longer has access to it. Any single thread can then thread::attach the channel to gain access to it.
thread::errorproc ?proc?	Registers a procedure to handle errors that occur when performing asynchronous thread::send commands. When called, proc receives two argument: the ID of the thread that generated the error, and the value of that thread's errorInfo variable.
thread::eval ?-lock mutex? arg ?arg...?	Concatenates the arguments and evaluates the resulting script under the mutex protection. If no mutex is specified, an internal static one is used for the duration of the evaluation.
thread::exists id	Returns boolean indicating whether or not the specified thread exists.
thread::id	Returns the current thread's ID.
thread::join id	Blocks until the target thread terminates. (Available only with Tcl 8.4 or later.)
thread::mutex create	Returns a token for a newly created mutex.
thread::mutex destroy mutex	Destroys the mutex.
thread::mutex lock mutex	Locks the mutex, blocking until it can gain exclusive access.
thread::mutex unlock mutex	Unlocks the mutex.
thread::names	Returns a list of the IDs of all running threads.
thread::preserve ?id?	Increments the reference count of the indicated thread, or the current thread if no id is given.
thread::release ?-wait? ?id?	Decrements the reference count of the indicated thread, or the current thread if no id is given. If the reference count is 0 or less, mark the thread for termination. If -wait is specified, the command blocks until the target thread terminates.
thread::send ?-async? id script ?varname?	Sends the script, to thread id. If -async is specified, do not wait for script to complete. Stores the result of script in varname, if provided.
thread::transfer id channel	Transfers the open channel from the current thread to the main interpreter of the target thread. This command blocks until the target thread incorporates the channel. (Available only with Tcl 8.4 or later.)
thread::unwind	Terminates a prior thread::wait to cause a thread to exit. Deprecated in favor of thread::release.
thread::wait	Enters the event loop.

The thread::configure command allows an application to query and set thread configuration options, in much the same way as the fconfigure command configures channels. Table 21-2 lists the available thread configuration options.

Table 21-2. Thread configuration options

-eventmark int	Specifies the maximum number of pending scripts sent with thread::send that the thread accepts. Once the maximum is reached, subsequent thread::send messages to this script block until the number of pending scripts drops below the maximum. A value of 0 (default) allows an unlimited number of pending scripts.
-unwindonerror boolean	If true, the thread "unwinds" (terminates its event loop) on uncaught errors. Default is false.

The tsv Namespace

The tsv namespace contains all of the commands for creating and managing thread shared variables. Table 21-3 describes all of the commands contained in the tsv namespace.

Table 21-3. The commands of the tsv namespace

tsv::append array element value ?value ...?	Appends to the shared variable like append.
tsv::exists array ?element?	Returns boolean indicating whether the given element exists, or if no element is given, whether the shared array exists.
tsv::get array element ?varname?	Returns the value of the shared variable. If varname is provided, the value is stored in the variable, and the command returns 1 if the element existed, 0 otherwise.
tsv::incr array element ?increment?	Increments the shared variable like incr.
tsv::lappend array element value ?value ...?	Appends elements to the shared variable like lappend.
tsv::lindex array element index	Returns the indicated element from the shared variable, similar to lindex.
tsv::linsert array element index value ?value ...?	Atomically inserts elements into the shared variable, similar to linsert, but actually modifying the variable.
tsv::llength array element	Returns the number of elements in the shared variable, similar to llength.
tsv::lock array arg ?arg ...?	Concatenates the args and evaluates the resulting script. During script execution, the command locks the specified shared array with an internal mutex.
tsv::lpop array element ?index?	Atomically deletes the value at the index list position from the shared variable and returns the value deleted. The default index is 0.
tsv::lpush array element value ?index?	Atomically inserts the value at the index list position in the shared variable. The default index is 0.
tsv::lrange array element first last	Returns the indicated range of elements from the shared variable, similar to lrange.
tsv::lreplace array element value ?value ...?	Atomically replaces elements in the shared variable, similar to lreplace, but actually modifying the variable.
tsv::lsearch array element ?mode? pattern	Returns the index of the first element in the shared variable matching the pattern, similar to lsearch. Supported modes are: -exact, -glob (default), and -regexp.
tsv::move array old new	Atomically renames the shared variable from old to new.
tsv::names ?pattern?	Returns a list of all shared variable arrays, or those whose names match the optional glob pattern.
tsv::object array element	Creates and returns the name of an accessor command for the shared variable. Other tsv commands are available as subcommands of the accessor to manipulate the shared variable.
tsv::pop array element	Atomically returns the value of the shared variable and deletes the element.
tsv::set array element ?value?	Sets the value of the shared variable, creating it if necessary. If value is omitted, the current value is returned.
tsv::unset array ?element?	Deletes the shared variable, or the entire array if no element is specified.

The tpool Namespace

The tpool namespace contains all of the commands for creating and managing thread pools. Table 21-4 describes all of the commands contained in the tpool namespace.

Table 21-4. The commands of the tpool namespace

tpool::create ?options?	Creates a thread pool, returning the thread pool's ID. Table 21-5 describes supported configuration options.
tpool::post tpoolId script	Sends a Tcl script to the specified thread pool for execution, returning the ID of the posted job. This command blocks (entering the event loop to service events) until a worker thread can service the job
tpool::wait tpoolId jobList ?varName?	Blocks (entering the event loop to service events) until one or more of the jobs whose IDs are given by the jobList argument are completed. Returns a list of completed jobs from jobList. If provided, varName is set to a list of jobs from jobList that are still pending.
tpool::get tpoolId jobId	Returns the result of the specified jobId. tpool::wait must have reported previously that the job is complete. If no error occurred in the job, the result is the return value of the last command executed in the job script. Any error encountered in job execution is in turn thrown by tpool::get, with the errorCode and errorInfo variables set appropriately.
tpool::names	Returns a list of existing thread pool IDs.
tpool::preserve tpoolId	Increments the reference count of the indicated thread pool.
tpool::release tpoolId	Decrements the reference count of the indicated thread pool. If the reference count is 0 or less, mark the thread pool for termination.

The tpool::create command supports several options for configuring thread pools. Table 21-5 lists the available thread pool configuration options.

Table 21-5. Thread pool configuration options

-minthreads number	The minimum number of threads. If the number of live threads in the thread pool is less than this number (including when the thread pool is created initially), new threads are created to bring the number up to the minimum. Default is 0.
-maxthreads number	The maximum number of threads.When a job is posted to the thread pool, if there are no idle threads and the number of existing worker threads is at the maximum, the thread posting the job blocks (in its event loop) until a worker thread is free to handle the job. Default is 4.
-idletime seconds	The maximum idle time, in seconds, before a worker thread exits (as long as the number of threads doesn't drop below the -minthreads limit). Default value is 0, meaning idle threads wait forever.
-initcmd script	A script that newly created worker threads execute.
-exitcmd script	A script that worker threads execute before exiting.