                           Notes on pSather
                           ================
            (C) by Norbert "Nobbi" Nemec <nobbi@gnu.org>
                  Erlangen/Germany, Sept 14, 1999

-------------------------------------------------------------------------

These are just some short notes to get you started on pSather. Real
documentation still is on the way and as it look, it may need some more
time. For now, perhaps try looking at the ICSI Sather site:

    http://www.icsi.berkeley.edu/~sather

Information there may be somewhat outdated, though, I'm afraid.

-------------------------------------------------------------------------

These last days, I have added a Brahma interface for linux LWP, that was
already included with this distribution. It is not very much tested or
debugged yet, but on my machine it compiles fine and the tests that were
included seem to be happy with it.

LWP is a non-preemptive user-space thread implementation, that should run
fine for any simulations. A implementation based on pthread/LinuxThreads
is on the way, but I'll need a little more time for that.

I did much debugging and restructuring of the build process outside the
linux/lwp platform as well, so I'm not sure I did not break any other
platforms. Unfortunately, I do not have any means to test those myself,
so please tell me, if you can help out at that point.


Compilation
===========

All you have to do to make use of pSather is first to chose a platform
capable of multithreading. In the case of linux/lwp, that means to change to

    PLATFORMS = linux,linux/lwp
    DEFAULT_PLATFORM = linux

in the main Makefile and compile

    make


Using pSather
=============

The pLibrary and the pSather language extensions are automatically activated
when you use a multi-threaded platform (like linux/lwp) So just add 
    -linux/lwp
to the sacomp-commandline and that's it. Have fun!


Internals
=========

Here is just a brief overview about the different libraries that you can
find in the Sather distribution. Much of this was being worked on when the
project was given up at ICSI, so I had to sort it out before I could start
working with it. Perhaps this will help you:

lwp - "Light Weight Processes"
	This is just a small implementation of user-space threads. I think 
	it came from outside Sather, but there is not much documentation there.
	This is a normal C-library with a clean interface (lwp.h), that should 
	work outside Sather just as well.
	
GC - "Boehm Garbage Collector"
	Not distributed with Sather any more. It is a garbage collector
	maintained outside of GNU Sather, that we just make use of.
	
Brahma
	This is just a small interface library to make pSather more easy to port.
	It is just a minimal wrapper around lwp, pthread, ActiveThreads or
	whatever the underlying thread library is. If you want to get pSather to
	work on some non-supported platform, only thing you need to do is to supply
	one short .c and one short .h file. Look at the lwp_linux ones for example.

Siva - A alternative experimental (?) Garbage Collector
	I do not knwo exactly what the state of this is, since I did not compile
	it yet. It is called a "zoned memory manager", i.e. for distributed
	computing. Obviously it was once meant to be a complete replacement for
	the GC. If anybody wants to look into this I'll be glad to hear more
	details.

ActiveThreads
am - "Active Messages"
	These two are two intermediate libraries which I did not use yet. AM did
	compile after some work, but I could not get the tests to work on my
	machine. ActiveThreads, I did not touch at all.

pSather
	There is one directory System/pSather/pSather, which contains several
	important C files. These are directly used by the classes in
	pLibrary/pSather and by the compiler-generated code itself.


----------------------------------------------------------------------------

Ok, I hope this information will help you get into the matter, I'll be glad to 
hear results. :-)

					Nobbi
