NAME

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

SYNOPSIS

thread::create?script?
thread::id
thread::errorproc procname
thread::exit
thread::names
thread::send id ?-async? script
thread::wait

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.

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

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.

SEE ALSO

A Guide to the Tcl Threading Model.