In-the-clear ("Transparent") STM
================================


These files build on Keir Fraser's lock-free library
(http://www.cl.cam.ac.uk/netos/lock-free) to provide a further STM
implementation which exposes a word-based interface.

See stm_holdrel.h for an overview of the interface.

See rb_stm_holdrel.c for example usage of the interface in defining a
red-black tree.


1. Building
-----------
This in-the-clear STM is designed only for SPARC/Solaris systems.  

By default it is configured to build for v8plus (32-bit pointers,
32-bit ints).  It should be straightforward to reconfigure it for v9
(64-bit pointers, 32-bit ints).

However, the only dependency should be between the holdrel.c file and
various Solaris functions for controlling thread scheduling.  Similar
facilities exist in (e.g.) Linux.


2. What you get
---------------
'stm_holdrel.c' is a word-based STM with the programming API defined
in 'stm_holdrel.h'. 

'holdrel.c' provides an implementation of the "hold" and "release"
operations defined in 'holdrel.h'.  This implementation uses
operations exported by the scheduler to allow one thread to adjust the
execution point of another thread.  We discuss alternative
implementations in a forthcoming paper.

A single major demo executable is built:
 
 rb_stm_holdrel       --- Red-black trees using hold-release STM

As with Keir Fraser's lock free package, the executable is run as: 
 <executable> <num_threads> <read_proportion> <key power>

'num_threads' indicates the degree of parallelism.

'read_proportion' determines what proportion of the random workload is
lookups as opposed to updates or removals. The proportion is out of 256.

'key_power' indicates the key range. Key range is 2 ^ 'key_power'.
Since updates and removals are equally probable, the mean set size 
will be 2 ^ ('key power' - 1).


3. Verifying correctness
------------------------
To check that each implementation correctly behaves as a 'set' ought
to, you can define DO_WRITE_LOG in 'set_harness.c'. This will cause
each implementation to produce a log describing each operation that
was executed, and its result.

This can be run through 'replay' which will serach for a linearisable
schedule.


4. Distribution license
-----------------------
The license is GPL. See the file COPYING for details.


 -- Tim Harris, 21st October 2003

