LockVizQuickStartGuide

Quick Start

Download Required Files

• You can download the executable jar file using the button below
• Also download the sample thread-dump for this tutorial

Loading the example thread-dump

1. Save the downloaded jar file somewhere appropriate and then double click on it. You should see the following:

• Click on the open button on the far left of the toolbar.
• You will see a file dialog. Please choose the example thread dump you downloaded as described above (example.tdump) or you can load your own thread dump generated via visual VM
• You should see the screen below:

Navigating the Model

• The thread dump has been loaded, parsed and a model created in memory.
• The main screen shows all of the thread, mutexes and their relationships. This is referred to as a MultiGraph. More on this later.
• The tree in the top left has the file loaded as the root and all of the Simple (sub-graphs) listed below it i.e. all the self referential groups of threads connected by mutexes. I will often refer to these simple graphs as an entanglement.

• Any entanglement of threads that are in a dead-locked state will be highlighted in red in the tree.

• Click on the node in the tree that is highlighted in red. This will open a new tab with only the deadlocked entanglement in.

• If you click in the main screen and use the mouse wheel you will zoom in and out
• You can drag the nodes to make them easier to see.
• If you click on a node then information about it is shown in the bottom left.
• If you click on a connection between the nodes you are shown information about the action on a mutex.

The elements of the diagram are as follows

• Square This is a Thread object. The colour means:
  • Green The thread is runnable
  • Orange The thread is waiting
  • Red The thread is blocked
• Circle This is a mutex
  • Blue This is a mutex based on an Object Monitor i.e. synchronized keyword
  • Cyan This is a mutex based on an ownable synchronizer i.e. java 1.5 style Lock object.
• Line This is a threads action on a mutex. The number of the line is the order the thread has taken that action. If you hover over this it shows you the stackline it is taken in.

In the previous screen shown we can easily see why this is a deadlock. We have two threads which are both trying to lock two resources in the same order. Each thread has locked a single mutex and is waiting on the second which is owned by the other thread.

Deeper Inspection

• You can right click on a thread object (Square) and select 'show stack'. This shows the stack for the thread and highlights lines where locks are successfully taken (green) and lines where the thread are blocked (red).

• You can right click on thread action (line) and choose 'Show line in stack'. This brings up the stack window, as you see for the thread, but highlights the line where corresponding to the thread action you have chosen.

When investigating a threading issue it can be useful to open multiple windows showing locking lines in stack traces.

From here

You can use LockViz to load up any thread-dumps you have generated (using VisualVM) from your own applications and start analysing!