Purpose: document the [Tcl] thread [extension], point to its online source code repository, etc.

**Thread Extension**

 What: Thread extension
 Where: http://tcl.sf.net/ 
 Description: This Tcl extension, with a thread-enabled core, allows script
        level access to run Tcl scripts within threads.
        Currently at version 2.6.5 .
 Updated: 12/2004
 Contact: See web site


See also [Threads]

People with an interest in this extension might also want to subscribe to the tcl-threads mailing list
[https://lists.sourceforge.net/mailman/listinfo/tcl-threads]
on [SourceForge].

----
***Documentation***
During 2006, there are man pages for the various packages in the thread module found at sf.net:

   * '''[http://tcl.cvs.sourceforge.net/*checkout*/tcl/thread/doc/html/thread.html%|%thread]'''(n) - script access to tcl threading
   * '''[http://tcl.cvs.sourceforge.net/*checkout*/tcl/thread/doc/html/tpool.html%|%tpool]'''(n) - script access to the worker thread pool manager
   * '''[http://tcl.cvs.sourceforge.net/*checkout*/tcl/thread/doc/html/tsv.html%|%tsv]'''(n) - script level manipulation of data shared between threads
   * '''[http://tcl.cvs.sourceforge.net/*checkout*/tcl/thread/doc/html/ttrace.html%|%ttrace]'''(n) - trace based interpreter initialization

----
***Core thread commands***
    :   '''[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'''? ?'''-head'''? ''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::rwmutex]''' ...
    :   '''[thread::cond]''' ...

----
As of early 2004, the best documentation for the Thread extension appears in
"The Tcl Threading Model"
[http://www.tcl.tk/doc/howto/thread_model.html],
the Thread "[man]" page
[ftp://ftp.tcl.tk/pub/tcl/thread/thread21.html]
(the more recent counterpart from the CVS repository is 
[http://tcl.cvs.sourceforge.net/*checkout*/tcl/thread/doc/html/thread.html?rev=HEAD]), 
and a sample chapter
[http://www.beedub.com/book/4th/Threads.pdf]
from Brent's (et al.) book.
[dqkit] is a convenient deployment for those with
an interest in
======
  package require Thread
======

[snichols] Note: I've had problems with [dqkit] and Tcl threads. On a Win32 system in order to find packages in a child thread I had to put the package files outside of the starkit. Because of that its almost easier to just use a thread enabled Tcl interpreter instead of dqkit if the package files have to exist outside of the [starkit].

''[escargo] 29 Apr 2005'' - The first link above ("The Tcl Threading Model") eventually points to this site
ftp://ftp.tcl.tk/pub/tcl/thread/ that only has versions of thread up to 2.4,
and not the current 2.6.

[RLH] 2005-08-02: The files are here [http://sourceforge.net/project/showfiles.php?group_id=10894].

----
***Ttrace sub-package***
The 2.6 release adds a sub-package called Ttrace. This allows for easy propagation of
interpreter related resources ([procedure]s, [namespace]s, objects (for [XOTcl])). Usage
is trivial: yust wrap the code you want to replicate within ttrace::eval like this:

======
    package req Thread
    package req Ttrace

    for {set i 0} {$i < 4} {incr i} {
        set tid($i) [thread::create -preserved]
    }

    ttrace::eval {
        proc foo {args} {
           puts foo
        }
        proc bar {args} {
           puts bar
        }
    }
======

and execute this from any thread created by the thread extension. This will 
replicate the definitions of 'foo' and 'bar' to all existing threads. In the
above example, all 4 threads will be seeded. One very important design feature
of Ttrace is that resources are propagated in a lazy fashion. That is, nothing
is actually done in other threads until the resource gets referenced for the
first time. This is accomplished by overloading the [Tcl] [unknown] command.
So, when the [unknown] triggers, it tries to locate the resource definition 
by doing a lookup in the Ttrace private (in-memory) database first.
On hit, the definition is loaded on-the-fly in the current interpreter. 
On miss, the [unknown] processing is delegated down-the-road. This way, thread
startup and memory consumption are minimized. Thanks to [Vince Darley] for his
great command [trace] framework, which is used as the base for the Trace package.
For more information see 'man ttrace'.

----
***Threads and the event loop***
[Silas] 2006-12-17: By default threads that are not the main thread don't have an [event loop] (Am I wrong?). Do add it, insert a [[[vwait] forever]] or [[vwait ''your_variable'']] inside your '''thread::create''' block. <<br>> [AKM] 2006-10-26 I thought the advice was to use '''thread::wait''' so that the thread can be terminated with '''thread::release'''?

----
**Forth-style Threading**
A distinct meaning
[http://www.complang.tuwien.ac.at/forth/threaded-code.html]
of "thread" occurs in discussions of [bytecode], especially
when [Forth] is nearby.