= README = 


== BUILD ==

Just ''make all'' after you've got coThreads installed on your system. 

In case you want to play with the examples before really installing coThreads
on your system, you should first build coThreads in the ''src'' directory as
usual, then go the example directory and pass the building directory as $LOCAL
variable to make, e.g. ''make all LOCAL=../src''.

Type ''make clean'' to remove all imtermediate and final building results.


== LIST ==

* coth (use: Thread (or Cothread), Mutex)
  Simple test of mutex. A set of threads tries to grab a single mutex and
  release it for random times 

* evt (use: Thread (or Cothread), Event)
  Simple test of event. Most examples are directly from the OCaml OReilly
  book. The execution won't exist, this is intentional.

* lock (use: Thread (or Cothread), Mutex)
  Simple test of mutex. A set of threads try to grab two mutex. Each thread
  first must grab the first mutex before the second mutex, then release the
  second mutex and the first one.

* mcast (use: Thread (or Cothread), Stm)
  STM example from [1], contributed by Yoriyuki Yamagata

* merge (use: Thread (or Cothread), Stm)
  STM example from [1], contributed by Yoriyuki Yamagata

* mvar (use: Thread (or Cothread), Stm)
  STM example from [1], contributed by Yoriyuki Yamagata

* phil (use: Thread (or Cothread), Stm)
  Classical philosophers dinning problem written in STM. Launch it with 
  [./phil n], where n is the number of philosophers and chopsticks.

* ray_col, ray_nocol (use: Cothread, Event)
  Replanted versions of Jon Harrop's ray tracer [3]. ray.ml is the module
  containing common computation functions, ray_xxx.ml are parallel engines.
  In ray_nocol.ml, the workers don't send the results back to master, instead
  they write them directly to the output file; in ray_col.ml, the workers send
  results back to the master, and the master write them to the output file. 
  Launch it with [./ray_xxx level size degree outputfile], where [level] and
  [size] are about the quality of output image, and [degree] is the parallel
  degree which should equal or greater than the cores or cpus of your machine
  if you'd like to get the most speedup. Or you may just lanch it with
  [./ray_xxx] which takes the default setting [./ray_xxx 9 512 2 ray_xxx.pgm]

* santa (use: Thread (or Cothread), Stm)
  The Santa Clause problem documented in [2]. The haskell version is attached
  as comment at the end of the file.

* sing (use: Thread (or Cothread), Stm)
  Simple test of Stm. Two threads constantly update a single tvar.

* test (use: Thread (or Cothread), Stm)
  Simple test of Stm to calculate the sum of [0..n-1] with n threads. The i_th
  thread is responsible for adding i to the sum. Its action is not allowed to
  take place until the current sum exceed sum (i/10).

* The Makefile itself is an example. It shows that how you can build your
  applications against a set of execution engines with just a few lines of
  pattern rules. Note that we make use of the Cothread module for
  ''object-level compatability'' instead of the standard Thread module, though
  in most case you can switch it back, but then the Makefile will be a bit more
  complicated, as you have to compile a different version of object files for
  each of the engines.

[1] http://research.microsoft.com/users/simonpj/papers/stm/index.htm#composble
[2] https://research.microsoft.com/users/simonpj/papers/stm/index.htm#beautiful
[3] http://www.ffconsultancy.com/languages/ray_tracer/index.html
