
	MTtcl - Multi-threaded Tcl

Version 1.0

The MTtcl package gives Tcl/Tk programmers access to the multi-threading
features of Solaris 2.  The package comes in two parts; a patch to apply
to Tcl 7.4, and a Tcl threads extension.  Also included are man pages,
examples, and a 20-page tutorial.

MT-sturdy Tcl
-------------
Modifications are necessary to enable Tcl to work "safely" in the
presence of multiple threads.  The Tcl interpreter uses a number of
static and global variables to execute scripts.  If two threads are
using the same global, the behavior of the script is unpredictable.
This "safe" Tcl is called MT-sturdy Tcl.  It is created by applying
a patch to a fresh Tcl 7.4 source tree.
The changes made to Tcl are documented in "mtsturdy.doc" in this
directory.

Tcl threads
-----------
The threads extension brings threads programming into the Tcl
environment.  Multiple scripts can be interpreted 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 and a tutorial.

Tutorial
--------
The doc directory contains the Postscript and SGML source for a
tutorial I wrote about Tcl threads.  Examples used the tutorial
are in doc/examples.  Enjoy!


Changes in version 1.0
----------------------
This version of MTtcl is based on Tcl 7.4 and Tk 4.0.  It is compatible
with the two patches (p1 and p2) currently available.

The install method has changed.  Review INSTALL in this directory for
instructions.

The following improvements have been made since MTtcl0.9:

changes to Tcl threads
----------------------
Fixed: reentrancy bug in handling messages to Tk thread
Fixed: "array names" on shared array could return incomplete list
Added: "thread kill"
Fixed: removed need to include tclInt.h
Fixed: bug in "info procs"

More examples.  See examples/ and doc/examples/.

changes to MT-sturdy Tcl
------------------------
Fixed: The Tcl_Async* functions are now mt-safe
Fixed: The functions in tclCkalloc.c are now mt-safe

MT-sturdy Tcl is packaged as a patch instead of a copy of the entire
Tcl source tree.  New instructions have been added to INSTALL.


Changes in version 0.9
----------------------
This version of MTtcl includes all the major features slated for 1.0.
The one INCOMPATIBLE change made is the switch to Tcl7.4b3.  All future
MTtcl versions will only be available for Tcl7.4 or higher.

The following improvements have been made since MTtcl0.8:

Bad pointer accesses fixed
Memory leaks plugged
Fixed various dumb bugs
Fixed minor errors and omisions in the man pages
Detached threads are automatically cleaned up on thread exit
The variable "tcl_interactive" is set to 0 for non-interactive threads
The variable "auto_path" is inherited by new threads from the creating thread
Error returns are more consistent and stylistically similar to Tcl
Updated the countdown example to use new features

The following additions have been made:

Tcl procedures shared among threads.  It is no longer necessary to
	supply all the Tcl code to a thread when it is created.
	Procedures created with the proc command are shared among
	all Tcl threads in a process.  Procedure creation, destruction,
	and renaming affect all threads immediately.
Call "threaderror" when a non-interactive thread get an error while
	evaluating.  Default "threaderror" procs are provided in
	libtcl_thread and libtk_thread.  In Tk, the proc causes the
	standard tkerror dialog to pop-up.
New example Julia set calculator.  It's multi-threaded, dynamic, and
	very fast on my two processor Sparc 20.
"thread nextmsg" can take a time-out argument


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

	Solaris 2.3 or 2.4 on Sparc
	SparcWorks 3.0 or greater C compiler
	Tcl 7.4
	Tk 4.0

Other configurations may work, but they have not been tested.
Tk is needed only if you want to compile mtwish or the Tk based
examples.


Installation
------------
Instruction for building and installing can be found in INSTALL.


Other extensions
----------------
MT-sturdy Tcl has been used with numerous Tcl and Tk extensions and
programs.  The MT-sturdy tclsh passes the Tcl 7.4 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, ask on the comp.lang.tcl newsgroup, or send me email.


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.  Only one configuration tested.  Tcl 7.4b3.

1.0	Functionally complete, lots of testing, good examples.
	[Multiple Solaris configurations supported.]  Based on final
	Tcl 7.4 and Tk 4.0.  MT-sturdy Tcl distributed as patch
	rather than all the Tcl code.

Well, only one Solaris configuration is supported in version 1.0,
so I did not totally reach my goal.  Nor did I create a threaded
version of TclRobots.  Sigh, so many programs, so little time.

Beyond 1.0 I'd like to make MTtcl portable.  Thread APIs and OSs I intend
to support are:

	POSIX pthread
	Windows NT
	DCE pthread

POSIX will be my first priority.  Solaris 2.5 will include a POSIX pthread
implementation.  AIX 4.x will likely have a POSIX compliant thread interface.
I'll be doing some Windows NT programming in the near future, so that
port should be done sooner than I expected.

I don't know if my changes to Tcl will be rolled back into the official
Tcl releases.  There is some interest within the Tcl group at Sun.  I
intend to pursue that route, but John Ousterhout is a rather stubborn
nay-sayer of threads.


Availability
------------
The latest release will always be available via anonymous FTP from
	ftp.netcom.com:/pub/bo/booga/MTtcl1.0.tar.gz

It should also be available from
	ftp.aud.alcatel.com:/tcl/extensions/MTtcl1.0.tar.gz


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

*** I am in the process of leaving Sun.  To contact me, use the
*** above address!  Do not send email to my "sun.com" address.

*** NEVER FEAR!  I will continue to support MTtcl in my new job.
*** I will still be doing Solaris programming and have access
*** to email and the Internet.  Until all that is set-up at the
*** new company, please use booga@netcom.com.   Thanks!

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.

The tutorial in the doc directory includes detailed references.

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, Doug, and Tilman for comments and testing.


Steve Jankowski, booga@netcom.com
