NAME

thread - Create and manipulate threads with Tcl interpreters in them.

SYNOPSIS

thread::create ?-joinable? ?script?
thread::id
thread::exists id
thread::errorproc procname
thread::exit
thread::names
thread::send id ?-async? script
thread::wait
thread::join id
thread::transfer id channel

DESCRIPTION

The thread extension creates threads that contain Tcl interpreters, and it lets you send scripts to those threads.

thread::create creates a thread that contains a Tcl interpreter. The Tcl interpreter either evaluates the script, if specified, or it waits in the event loop for scripts that arrive via the thread::send command. The result of thread::create is the ID of the thread. The result, if any, of script is ignored. 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).

thread::id returns the ID of the current thread.

thread::errorproc sets a handler for errors that occur in other threads. Or, if no procedure is specified, the current handler is returned. By default, an uncaught error in a thread terminates that thread and causes an error message to be sent to the standard error channel. You can change the default reporting scheme by registering a procedure that is called to report the error. The proc is called in the interpreter that invoked the thread::errorproc command. The original thread that has the uncaught error is terminated in any case. The proc is called like this:

thread::exit terminates the current thread. There is no way to force another thread to exit - you can only ask it to terminate by sending it a command.

thread::names returns a list of thread IDs. These are only for threads that have been created via thread::create. If your application creates other threads at the C level, they are not reported by thread::names.

thread::exists 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.

thread::send passes a script to another thread and, optionally, waits for the result. If the -async flag is specified then the caller does not wait for the result. The target thread must enter its event loop in order to receive script messages. This is done by default for threads created without a startup script. Threads can enter the event loop explicitly by calling thread::wait or vwait.

thread::wait enters the event loop so a thread can receive messages from thread::send. This is equivalent to vwait unusedvariable.

thread::join waits for the thread with id id to exit and then returns its exit code. Errors will be returned for threads which are not joinable or already waited upon by another thread.

thread::transfer moves the specified channel from the current thread and interpreter to the main interpreter of the thread with the given id. After the move the current interpreter has no access to the channel anymore, but the main interpreter of the target thread will be able to use it from now on.

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. 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, vwait on variables, and so forth. For the transfer of bulk information it is possible to move channels between the threads.

SEE ALSO

A Guide to the Tcl Threading Model.