README for Mutex Comparison Toolkit v1.0
----------------------------------------

This is a set of kernel modules for experimenting with performance of
various Linux locking primitives for a classical "reader/writer problem"
including:

	o plain spinlocks
	o read/write spinlocks
	o plain binary semaphores
	o read/write binary semaphores
	o big reader read/write spinlocks

You can use these modules for determining which one yields the best
performance for your particular task size, expected load on the system
and any other constraints you may have. Varying the amount of time spent
in the critical region you can find the conditions that cause lock
contention and see which primitives are best suited. For example, comparing
rwlock.c and brlock.c I learnt that with default parameters (see src)
using brlock is actually much faster not just for readers but for writers
also despite the fact that "by the book" writers ought to be severely
penalized.

The name of each module corresponds to the type of primitive tested.
The modules are parametrized by:

	o nr - number of readers
	o nw - number of writers
	o tr - number of microseconds a reader spends in the critical section
	o tw - number of microseconds a writer spends in the critical section
	o T - total number of seconds for the test, default is -1 which means
	  run until user does rmmod

The typical invocation is:

# insmod rwlock.o nr=5 nw=1 T=40
# lsmod
Module                  Size  Used by
rwlock                  18368   6 
# lsmod
Module                  Size  Used by
rwlock                  18368   0 
# rmmod rwlock
# dmesg | tail -9
--------------------------------------------
r0: loops=957466 (23936/sec)
r1: loops=962742 (24068/sec)
r2: loops=960082 (24002/sec)
r3: loops=984250 (24606/sec)
r4: loops=968952 (24223/sec)
w0: loops=607540 (15188/sec)
Total time: 40 seconds
--------------------------------------------

Enjoy.


Comments, fixes and flames to Tigran Aivazian <tigran@veritas.com>