README revision 12027 
111265Sandreas.sandberg@arm.comThis is a source code distribution for QuickThreads.  QuickThreads is a
211265Sandreas.sandberg@arm.comtoolkit for building threads packages; it is described in detail in the
311265Sandreas.sandberg@arm.comUniversity of Washington CS&E Technical report #93-05-06, available via
411265Sandreas.sandberg@arm.comanonymous ftp from `ftp.cs.washington.edu' (128.95.1.4, as of Oct. '94)
511265Sandreas.sandberg@arm.comin `tr/1993/05/UW-CSE-93-05-06.PS.Z'.
611265Sandreas.sandberg@arm.com
711265Sandreas.sandberg@arm.comThis distribution shows basic ideas in QuickThreads and elaborates with
811265Sandreas.sandberg@arm.comexample implementations for a gaggle of machines.  As of October those
911265Sandreas.sandberg@arm.commachines included:
1011265Sandreas.sandberg@arm.com
1111265Sandreas.sandberg@arm.com	80386 faimly
1211265Sandreas.sandberg@arm.com	88000 faimily
1311265Sandreas.sandberg@arm.com	DEC AXP (Alpha) family
1411265Sandreas.sandberg@arm.com	HP-PA family
1511265Sandreas.sandberg@arm.com	KSR
1611265Sandreas.sandberg@arm.com	MIPS family
1711265Sandreas.sandberg@arm.com	SPARC V8 family
1811265Sandreas.sandberg@arm.com	VAX family
1911265Sandreas.sandberg@arm.com
2011265Sandreas.sandberg@arm.comConfiguration, build, and installation are described in INSTALL.
2111265Sandreas.sandberg@arm.com
2211265Sandreas.sandberg@arm.comBe aware: that there is no varargs code for the KSR.
2311265Sandreas.sandberg@arm.com
2411265Sandreas.sandberg@arm.comThe HP-PA port was designed to work with both HP workstations
2511265Sandreas.sandberg@arm.comand Convex SPP computers. It was generously provided by Uwe Reder
2611265Sandreas.sandberg@arm.com<uereder@cip.informatik.uni-erlangen.de>. It is part of the ELiTE
2711265Sandreas.sandberg@arm.com(Erlangen Lightweight Thread Environment) project directed by 
2811265Sandreas.sandberg@arm.comFrank Bellosa <bellosa@informatik.uni-erlangen.de> at the Operating 
2911265Sandreas.sandberg@arm.comSystems Department of the University of Erlangen (Germany).
3011265Sandreas.sandberg@arm.com
3111265Sandreas.sandberg@arm.comOther contributors include: Weihaw Chuang, Richard O'Keefe,
3211265Sandreas.sandberg@arm.comLaurent Perron, John Polstra, Shinji Suzuki, Assar Westerlund,
3311265Sandreas.sandberg@arm.comthanks also to Peter Buhr and Dirk Grunwald.
3411265Sandreas.sandberg@arm.com
3511265Sandreas.sandberg@arm.com
3611265Sandreas.sandberg@arm.comHere is a brief summary:
3711265Sandreas.sandberg@arm.com
3811265Sandreas.sandberg@arm.comQuickThreads is a toolkit for building threads packages.  It is my hope
3911265Sandreas.sandberg@arm.comthat you'll find it easier to use QuickThreads normally than to take it
4011265Sandreas.sandberg@arm.comand modify the raw cswap code to fit your application.  The idea behind
4111265Sandreas.sandberg@arm.comQuickThreads is that it should make it easy for you to write & retarget
4211265Sandreas.sandberg@arm.comthreads packages.  If you want the routine `t_create' to create threads
4311265Sandreas.sandberg@arm.comand `t_block' to suspend threads, you write them using the QuickThreads
4411265Sandreas.sandberg@arm.com`primitive' operations `QT_SP', `QT_INIT', and `QT_BLOCK', that perform
4511265Sandreas.sandberg@arm.commachine-dependent initialization and blocking, plus code you supply for
4611265Sandreas.sandberg@arm.comperforming 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