README revision 12027 
1This is a source code distribution for QuickThreads.  QuickThreads is a
2toolkit for building threads packages; it is described in detail in the
3University of Washington CS&E Technical report #93-05-06, available via
4anonymous ftp from `ftp.cs.washington.edu' (128.95.1.4, as of Oct. '94)
5in `tr/1993/05/UW-CSE-93-05-06.PS.Z'.
6
7This distribution shows basic ideas in QuickThreads and elaborates with
8example implementations for a gaggle of machines.  As of October those
9machines included:
10
11	80386 faimly
12	88000 faimily
13	DEC AXP (Alpha) family
14	HP-PA family
15	KSR
16	MIPS family
17	SPARC V8 family
18	VAX family
19
20Configuration, build, and installation are described in INSTALL.
21
22Be aware: that there is no varargs code for the KSR.
23
24The HP-PA port was designed to work with both HP workstations
25and Convex SPP computers. It was generously provided by Uwe Reder
26<uereder@cip.informatik.uni-erlangen.de>. It is part of the ELiTE
27(Erlangen Lightweight Thread Environment) project directed by 
28Frank Bellosa <bellosa@informatik.uni-erlangen.de> at the Operating 
29Systems Department of the University of Erlangen (Germany).
30
31Other contributors include: Weihaw Chuang, Richard O'Keefe,
32Laurent Perron, John Polstra, Shinji Suzuki, Assar Westerlund,
33thanks also to Peter Buhr and Dirk Grunwald.
34
35
36Here is a brief summary:
37
38QuickThreads is a toolkit for building threads packages.  It is my hope
39that you'll find it easier to use QuickThreads normally than to take it
40and modify the raw cswap code to fit your application.  The idea behind
41QuickThreads is that it should make it easy for you to write & retarget
42threads packages.  If you want the routine `t_create' to create threads
43and `t_block' to suspend threads, you write them using the QuickThreads
44`primitive' operations `QT_SP', `QT_INIT', and `QT_BLOCK', that perform
45machine-dependent initialization and blocking, plus code you supply for
46performing the portable operatons.  For example, you might write:
47
48	t_create (func, arg)
49	{
50	  stk = malloc (STKSIZE);
51	  stackbase = QT_SP (stk, STKSIZE);
52	  sp = QT_INIT (stakcbase, func, arg);
53	  qput (runq, sp);
54	}
55
56Threads block by doing something like:
57
58	t_block()
59	{
60	  sp_next = qget (runq);
61	  QT_BLOCK (helper, runq, sp_next);
62	  // wake up again here
63	}
64
65	// called by QT_BLOCK after the old thread has blocked,
66	// puts the old thread on the queue `onq'.
67	helper (sp_old, onq)
68	{
69	  qput (onq, sp_old);
70	}
71
72(Of course) it's actually a bit more complex than that, but the general
73idea is that you write portable code to allocate stacks and enqueue and
74dequeue threads.  Than, to get your threads package up and running on a
75different machine, you just reconfigure QuickThreads and recompile, and
76that's it.
77
78The QuickThreads `distribution' includes a sample threads package (look
79at stp.{c,h}) that is written in terms of QuickThreads operations.  The
80TR mentioned above explains the simple threads package in detail.
81
82
83
84If you do use QuickThreads, I'd like to hear both about what worked for
85you and what didn't work, problems you had, insights gleaned, etc.
86
87Let me know what you think.
88
89David Keppel <pardo@cs.washington.edu>
90