## NAME

thread -
A Tcl extension implementing script level access to Tcl threading capabilities.

## SYNOPSIS

    package require Thread ?2.4?

    thread::create ?-joinable? ?script?
    thread::preserve id
    thread::release ?-wait? id
    thread::id
    thread::errorproc ?procname?
    thread::unwind
    thread::exit
    thread::names
    thread::exists
    thread::send id ?-async? script ?varname?
    thread::wait
    thread::join id
    thread::configure id ?option? ?value? ?option value?...
    thread::transfer id channel

    thread::cond options
    thread::mutex options

    tsv::names ?pattern?
    tsv::object array element
    tsv::set array element value
    tsv::get array element ?varname?
    tsv::unset array ?element?
    tsv::exists array ?element?
    tsv::pop array element
    tsv::move array old new
    tsv::incr array element ?increment?
    tsv::append array element value ?value ...?
    tsv::lappend array element value ?value ...?
    tsv::linsert array element index value ?value ...?
    tsv::lreplace array element first last ?value ...?
    tsv::llength array element
    tsv::lindex array element index
    tsv::lrange array element first last
    tsv::lsearch array element ?mode? pattern
    tsv::lpop array element ?index?
    tsv::lpush array element value ?index?

## DESCRIPTION

The thread extension creates threads that contain Tcl interpreters, and it lets you send scripts to those threads for evaluation. It also enables you to share data between threads in a safe, protected fashion. Additionaly, it provides script-level access to basic thread synchronization 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? ?script?
  This command 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 command).
thread::preserve id
  This procedure 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.

  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, using the thread::release command, caller signalizes that he/she has finished using the thread.

thread::release ?-wait? id
  This procedure decrements the thread reference counter. Each call to this command decrements the reference counter by one (1). Command returns the value of the reference counter after the decrement. When the reference counter reaches zero (0), the target thread is terminated.

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

thread::id
  This command returns the ID of the current thread.
thread::errorproc
  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 proc is called in the interpreter that invoked the thread::errorproc command. The proc is called like this:

      myerrorproc thread_id errorInfo

thread::unwind
  This stops a prior thread::wait. Execution of the script will continue from the thread::wait command. If thread::wait was the last command in a thread, the thread will exit. The command usually returns empty result but may trigger Tcl error with the message "target thread died" in some situations.
thread::exit
  This forces a thread stuck in the thread::wait to unconditionaly exit. This 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.

  Use of this command is deprecated in favour of the thread::unwind command or more advanced thread reservation system implemented with thread::preserve and thread::release commands. Use on your own risk and with extreme precaution. The command usually 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. If your application creates other threads at the C level, they are not reported by the thread::names command.
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 command.
thread::send
  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 vwait.

  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.

thread::wait
  This enters the event loop so a thread can receive messages from thread::send. This is equivalent to `vwait unusedvariable` except that thread::unwind will not unblock a vwait.
thread::join
  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.
thread::configure
  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 boolean -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
  This 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. 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.

This section describes commands used for script-level access to most common and basic thread synchronization primitives: mutexes and condition variables.

thread::mutex options
  This command provides script-level access to mutexes. Mutexes are most common thread synchronization primitives. They are used to synchronize access from two or more threads to one or more shared resources. Care has to be taken when using mutexes in an multithreading program. Improper use of mutexes may lead to various deadlock situations.

  The thread::mutex command supports following subcommands and options:

  thread::mutex create
    Creates the mutex and returns it's opaque handle. This handle should be used for any future reference to the newly created mutex.
  thread::mutex destroy mutex
    Destroys the mutex mutex. Extreme care has to be taken that nobody is using the mutex, otherwise unexpected errors may happen.
  thread::mutex lock mutex
    Locks the mutex mutex. Locking the mutex may deadlock the program if same thread attempts to lock the same mutex twice without unlocking it in between.
  thread::mutex unlock mutex
    Unlocks the mutex mutex so some other thread may lock it again.
thread::cond options
  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 a mutex.

  The thread::cond 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 (see `thread::cond notify`) or the optional timer has expired. The mutex must be locked by the calling thread on entrance to `thread::cond wait`. While waiting on the cond, the command releases mutex. Before returning to the calling thread, the command re-acquires 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 milliseconds the command waits to be signalled. Otherwise the command waits 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
        }
        thread::mutex unlock

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

This section describes commands implementing thread shared variables. A thread shared variable is very similar to a Tcl array but in contrast to a Tcl array it is created in thread-shared memory and can be accessed from many threads at the same time. Important feature of thread shared variable is that each access to the variable is internaly protected by a mutex so script programmer does not have to take care about locking the variable himself.

tsv::names
  Returns names of shared variables matching optional pattern or all known variables if pattern is ommited.
tsv::object
  Creates object accessor command for the element in the given shared array. Using this command, one can apply most of the other shared variable commands as method functions of the element object command:

      % tsv::set foo bar "A shared string"
      % set string [tsv::object foo bar]
      % $string append " appended"
      => A shared string appended

tsv::set
  Sets the value of the element in the shared array to value and returns the value. The value may be ommited, and the command will return the current value of the element. If the element cannot be found, error is triggered.
tsv::get
  Retrieves a value of the element located in the shared array. The command triggers error if the element is not found. If the optional varname is given, the value is stored in the named variable. In this case, the command returns true (1) if element is found or false (0) if the element is not found.
tsv::unset
  Deletes the element in the shared array. If the element is not given, it deletes the whole array.
tsv::exists
  Checks wether the element exists in the shared array. If the element is not given it tests the existence of the array itself. Returns true (1) if the item exists, false (0) if not.
tsv::pop
  Returns value of the element in the shared array variable and unsets the element in one atomic operation.
tsv::move
  Renames the element old to new in the shared array. This effectively performs an get/unset/set sequence of operations but in one atomic step.
tsv::incr
  Similar to standard Tcl incr but increments the value of the element in shared array instead of the Tcl variable.
tsv::append
  Similar to standard Tcl append but appends one or more values to the element in the shared array instead of the Tcl variable.
tsv::lappend
  Similar to standard Tcl lappend but appends one or more values to the list element in the shared array instead of the Tcl variable.
tsv::linsert
  Similar to standard Tcl linsert but inserts one or more values at the index list position in the list element in the shared array instead of the Tcl variable.
tsv::lreplace
  Similar to standard Tcl lreplace but replaces one or more values from the list element in the shared array instead of the Tcl variable.
tsv::llength
  Similar to standard Tcl llength but returns length of the list element in the shared array instead of the Tcl variable.
tsv::lindex
  Similar to standard Tcl lindex but returns value at the index list position from the list element in the shared array instead of the Tcl variable.
tsv::lrange
  Similar to standard Tcl lrange but returns values between first and last list position from the list element in the shared array instead of the Tcl variable.
tsv::lsearch
  Similar to standard Tcl lsearch but searches the list element in the shared array instead of the Tcl variable.
tsv::lpop
  Splices out the value at the index list position from the list element in the shared array. If index is not specified, it defaults to zero.
tsv::lpush
  Inserts the value at the index list position in the list element in the shared array. If index is not specified, it defaults to zero.
tsv::array
  This command supports most of the options of the standard Tcl array command like:
  tsv::array set
    Does the same as standard Tcl `array set`
  tsv::array get
    Does the same as standard Tcl `array get`
  tsv::array names
    Does the same as standard Tcl `array names`
  tsv::array size
    Does the same as standard Tcl `array size`
  tsv::array reset
    Does the same as standard Tcl `array set` but it clears the array and sets new values atomically.

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

In addition, this extension provides simple but effective way of threads to access thread-shared data without the need of explicit locking. This is implemented with shared variable arrays. Shared variable array is a data structure similar to Tcl array but internaly protected with mutex. Several threads can access array elements without synchronizing themselves. Script programmer can create any number of such arrays and access them or their elements from any thread, without explicit locking.

For advanced multithreading scripts, script-level access to two basic synchronization primitives, mutex and condition variables, is also supported.

## CREDITS

Shared variable arrays are inspired by the nsv interface found in AOLserver 3.+ highly scalable Web server from America Online.

## SEE ALSO

Guide to the Tcl threading model

## KEYWORDS

threads, events, message passing, synchronization, shared variables, mutex, condition variable