
	MTtcl - Multi-threaded Tcl

Version 0.8

The MTtcl package gives Tcl/Tk programmers access to the multi-threading
features of Solaris 2.  The package comes in two parts; a modified version
of Tcl 7.3, and a Tcl threads extension.

MT-sturdy Tcl
-------------
Modifications were necessary to enable Tcl to work "safely" in the
presence of multiple threads.  The Tcl interpretter uses a number of
static and global variables to execute scripts.  If two threads are
using the same global, the behavior of the script may be unpredictable.
This "safe" Tcl is called MT-Sturdy Tcl.

Tcl threads
-----------
The threads extension brings multi-thread programming into the Tcl
environment.  Multiple scripts can be interpretted simultaneously
with communication and synchronization between scripts.  There is
special support for using threads in Tk scripts.  Documentation for
the threads commands are in the form of man pages.


Dependencies
------------
To use MTtcl 0.8, you will need the following components:

	Solaris 2.3 on Sparc
	SparcWorks 3.0 C compiler
	Tcl 7.3
	Tk 3.6

Other configurations may work, but they have not been tested.  Tcl
isn't scrictly necessary, since all the Tcl source code is included in
MTtcl.  But, the package does not include any of the man pages,
examples, tests, or compatibility code of Tcl.  Tk is needed only if
you want to compile mtwish.


Installation
------------
The three directories of MTtcl are each installed separately.  See
the INSTALL file in the top-level directory for instructions.


Other extensions
----------------
MT-sturdy Tcl has been used with numerous Tcl and Tk extensions and
programs.  The MT-sturdy tclsh passes the Tcl 7.3 test suite.
We've never had a problem using this version of Tcl with other
code.  <knock-on-wood>

On the other hand, care must be taken when using Tcl threads with
other extensions.  The safest thing is to only use extensions in
the main thread (thread1).  Threads created by a Tcl program should
only use commands from the Tcl core and from the Tcl threads
extension.  This isn't as restrictive as it sounds.  Communicating
between threads is very easy, similar to the Tk send command.

Some extensions may be safe to use with Tcl threads, but determining
their level of safety is tricky.  A sure sign of trouble is use of
global and static variables.  Contact the author of the extension
for advice, or ask on the Tcl newsgroup, comp.lang.tcl.


Release plans
-------------
MTtcl will be released in at least three versions.

0.8	Most of the functionality, fairly robust, few examples or
	demonstrations.  The MTtcl APIs are not set in stone.
	Only one configuration tested.

0.9	All the functionality, more testing, more examples.  May not
	be API compatible with 0.8, but the API shouldn't change before
	1.0.  Testing on multiple configurations (Solaris only).

1.0	Functionally complete, lots of testing, good examples.
	Multiple Solaris configurations supported.

One of the examples for 1.0 will be a version of TclRobots that uses
threads instead of multiple processes.


Copyright
---------
Copyright (c) 1994 Sun Microsystems, Inc. - All Rights Reserved.

Permission is hereby granted, without written agreement and without
license or royalty fees, to use, copy, modify, and distribute this
software and its documentation for any purpose, provided that the
above copyright notice and the following two paragraphs appear in
all copies of this software.

IN NO EVENT SHALL SUN MICROSYSTEMS INC. BE LIABLE TO ANY PARTY FOR
DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF SUN MICROSYSTEMS
INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

SUN MICROSYSTEMS INC. SPECIFICALLY DISCLAIMS ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
ON AN "AS IS" BASIS, AND SUN MICROSYSTEMS INC. HAS NO OBLIGATION TO
PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.


Availability
------------
The latest release will always be available via anonymous FTP
from ftp.aud.alcatel.com in /tcl/extensions as MTtcl<version>.tar.gz


Help
----
Send me email if you need help:  booga@eng.sun.com

If you don't know anything about multi-thread programming, check out
a computer bookstore for good operating system books.  I learned
MT programming on-the-fly, but I had access to people vastly more
knowledgable.  The _Guide to Multithreaded Programming_ for Solaris
2.4 is a good document for the mechanics of threading.

Debugging multi-thread programs can be difficult if you don't have
the right tools.  The version of dbx that comes with SparcWorks 3.0
has good support for MT debugging.  Note that you need a special
license to enable these features.


Thanks
------
To Rafael and Doug for comments and testing.


Steve Jankowski, booga@eng.sun.com
SunSoft, Mountain View CA
