dlock is a lock debug library.
It tracks down the calls to the pthread_{spin,mutex}_{un,}lock functions
and keeps track of the lock usage.
Lock usage patterns are subsequently available as a dump, either
by calling ordering_dump() or by sending a signal if the appropriate
flags have been set in the DLOCK_FLAGS environment variable.

A) Introduction
===============

dlock is available in two flavors:
- compile time: instrumentation of the code is done through the
{SPIN,MUTEX}_* API.
- run time: dlock is loaded on the fly, but some information such as
the name of the lock, its location in the source code, won't be available.

If you don't have access to the source code of the program that you're
inspecting or if you don't want to go through the hassle of changing
your pthread_{spin,mutex}_* calls, jump to "B) Compile time usage".
If you want nice reports and details about the locks, go to "C) Run
time usage".

In any case, go to "D) Controlling dlock behaviour"

B) Compile time usage
=====================

With this method, you will need:
- access to the source code of the program to be observed.
- use MUTEX_INIT, MUTEX_LOCK and MUTEX_UNLOCK instead of
pthread_mutex_init, pthread_mutex_lock and pthread_mutex_unlock
respectively
- use SPIN_INIT, SPIN_LOCK and SPIN_UNLOCK instead of
pthread_spininit, pthread_spin_lock and pthread_spinunlock
respectively
- compile your program with the -DDLOCK flag

C) Run time usage
=====================

This method is a lightweight one, you don't have to recompile your
code whatsoever, you'll only need the libdlock.so shared library installed
on your system.
This lightweightness has its drawbacks however: mutexes will only be
known by their address. You'll be told if there's a problem with the
lock ordering of the observed program, but you'll probably need to go
through a recompile (ie method described in B) if you want more useful
information, and in particular the name and the location of the lock.

D) Controlling dlock behaviour
==============================

dlock is controlled by the means of environment variables, the main one
being DLOCK_FLAGS.
DLOCK_FLAGS must be an integer, and is treated as a bit field. Each bit
corresponds to a dlock feature.

Bit 0: DLOCK_INIT_CALIBRATE, if this bit is set, dlock will start a
calibrating loop before doing anything. This calibrating loop will
estimate the processor's running speed, and will thus display accurate
"held times" for the locks.

Bit 1: DLOCK_INIT_HANDLE_USR1, if this bit is set, dlock will install a
signal handler to catch the SIGUSR1 signal. Upon the signal's reception,
dlock will display the locks currently known to it, as well as their
ordering

Bit 2: DLOCK_INIT_HANDLE_USR2, if this bit is set, dlock will install a
signal handler to catch the SIGUSR2 signal. Upon the signal's reception,
dlock will display the locks currently known to it, as well as their
ordering

Bit 3: DLOCK_REGISTER_ATEXIT, if this bit is set, dlock will call atexit.
Upon the programs's termination, dlock will display the locks known to
it, as well as their ordering.

Bit 4: DLOCK_LOG_FILE, if this bit is set, dlock will log to a file
instead of printing to stderr. The name of the file is defined by the
DLOCK_LOG_FILE environment variable. Note that if the latter is not
defined, dlock fallsback to stderr printing.

Special behaviour: if dlock is used in runtime mode, and if no flags are
defined, it automatically registers the DLOCK_INIT_HANDLE_USR1 flag. This
is to allow doing something useful if you're running at runtime.

E) Reading dlock dumps
======================

dlock distribution comes with test_noinst and test_inst programs. Both
behave identically, except for the fact that test_noinst uses a plain
POSIX thread API, whereas test_inst uses the dlock {SPIN,MUTEX}_* API.

If you want to have a quick look at what dlock can bring you, just launch
./test_inst after building dlock.

To try an uninstrumented version, launch:
"LD_PRELOAD=./libdlock.so ./test_noinst"
and kill -SIGUSR1 $(pidof test_noinst) from another shell.

It should print a message along the lines of:

	********************************************************************************
	Registered lock sequences:
	held 0 ms, length: 2, times 1
	mutexA
	\-----> mutexB
	\-----> mutexC
	held 0 ms, length: 1, times 1
	mutexC
	held 0 ms, length: 1, times 1
	mutexD
	held 0 ms, length: 2, times 1
	mutexA
	\-----> mutexB
	********************************************************************************
	Thread list:
	[3079846816] no mutexes held
	[3079849648]
	mutexE (locked)
	\-----> mutexD
	********************************************************************************
	Mutexes known to dlock:
	        0x8049eac mutexA=/home/def/Prog/dlock/test_inst.c:45
	                depends on:
	        0x8049ef4 mutexB=/home/def/Prog/dlock/test_inst.c:46
	                depends on:
	                0x8049eac
	        0x8049ec4 mutexC=/home/def/Prog/dlock/test_inst.c:47
	                depends on:
	                0x8049eac
	        0x8049f0c mutexD=/home/def/Prog/dlock/test_inst.c:48
	                depends on:
	                0x8049edc
	        0x8049edc mutexE=/home/def/Prog/dlock/test_inst.c:49
	                depends on:
	

The dlock dump is divided in three parts:
1) The locking sequences (ie. an order to take locks) known to dlock
   This dumps:	- the max length the lock has been held
		- the length (depth) of the tree lock
		- the number of times this given sequence has been used in the program
		- a tree representing the order in which the locks have been taken
2) The threads known to dlock, and the locks that those threads are holding
3) The locks known to dlock
   This dumps:	- the address of the lock (mutex or spinlock)
		- it's name and location in the source file (only
		available in the instrumented version)
		- the addresses of the locks it depends on (ie. the
		locks taken directly before this one was taken)