vmlens Manual

Introduction

vmlens traces your application as a java agent and records all field, monitor and lock accesses. After you stop your program vmlens analysis the trace.

Getting started using eclipse

Install in eclipse

Install from marketplace:

  1. Start Eclipse (version 4.4 or greater)
  2. Drag to your running Eclipse* workspace. *Requires Eclipse Marketplace Client

Or if this does not work, install from update site:

  1. Start Eclipse
  2. Select Help>Install New Software…
  3. Work with: http://download1.vmlens.com/site/

Run a test

To run a unit test use the junit vmlens shortcut:

To run a different type of application use the "vmlens All Applications" run configuration, as described here. The configuration for junit and all other applications is described here.

The report

After the test run finished vmlens shows you the "vmlens Explorer" and the "vmlens Issues" view. The "vmlens Issues" view shows you all found data races, the symbol , and deadlocks, the symbol :

The other view, the "vmlens Explorer" view, shows you the last run of interleaved methods. Interleaving of methods is described here

Getting started using maven

Configure in maven

To use vmlens with maven, configure the following two tags in your pom.xml:

  1. a pluginRepository tag to tell maven to download the vmlens maven plugins from the url http://vmlens.com/download
  2. a plugin tag to tell maven that the vmlens plugin should be executed at the test phase.

The following example pom.xml shows you what to configure in your maven pom.xml to use use the vmlens interleave plugin. This table gives an overview of the three vmlens maven plugins. The configuration of the three plugins is described here.

<project>
      ...
<pluginRepositories>
  <pluginRepository>
    <id>vmlens</id>
    <url>http://vmlens.com/download</url>
  </pluginRepository>
</pluginRepositories>
     ...  
<build>
  <plugins>
    <plugin>
    <groupId>com.vmlens</groupId>
    <artifactId>interleave</artifactId>
    <version>1.0.1</version>
    <executions>
      <execution>
        <goals>
          <goal>test</goal>
        </goals>
      </execution>
    </executions>
    </plugin>
     ...
    </plugins>
</build>
      ...
</project>

The vmlens interleave maven plugin let you find race conditions and deadlocks in your test. It enables you to test all thread interleavings as described here

The report

After the test stopped, vmlens generates two html files, index.html, and elements.html in the folder target/vmlens-reports. The index.html file shows you all found data races, the symbol , and deadlocks, the symbol :

The other file, the elements.html file, shows you the last run of interleaved methods. Interleaving of methods is described here

What to test

You do not need to test everything with multithreaded tests. Only the parts of your application in which multiple threads access the same memory location or monitor needs to be tested using multi-threaded tests.

To see in which methods a memory location is accessed by multiple threads use the mode "state" in eclipse or the plugin "state" in maven. In this mode or maven plugin vmlens shows you the call hierarchy together with the fields and array which are accessed by multiple threads:

The level in this view shows the position of the method in the call hierarchy. So the main method and all methods overriding the run method of the class Thread are in level 0. Level 1 contains all methods called by those methods directly ans so on.

The fields and arrays shown for a specific method are either directly accessed by this method or indirectly by a method called by this method.

To choose which methods to test choose the methods you are developing at the highest level in the call hierarchy and test them as described here... By using the trace configuration, vmlens only shows you methods in a specific package or class, as described here for maven and here for Eclipse.

To see in which method a monitor is accessed, use the mode "monitor" in eclipse or the plugin "monitor" in maven.

Similar to the view in the mode state this view shows you the call hierarchy of all methods. Again the level in this view shows the position of the method in the call hierarchy. The row "Contains Monitors?" shows you if a method is synchronized or contains a synchronized block. The attribute "Called Methods Contains Monitors?" shows you if one of the methods called by this method is synchronized or contains a synchronized block.

How to test

We need to test that all multi-threaded accesses to the same memory location are correctly coordinated. To test all thread interleavings vmlens inserts wait, notify instruction during the test run and reruns all tests till all thread interleaving are tested. Let us look at a test for a counter to see how this works:

public class TestVolatileCounter {
	volatile int i = 0;
	@Test
	public void testCounter() throws InterruptedException 	{
		ExecutorService executor = Executors.newFixedThreadPool(2);
		executor.execute( () -> { addOne();   }  );
		executor.execute( () -> { addOne();   }  );
		executor.shutdown();
		executor.awaitTermination(10, TimeUnit.MINUTES);
	}
	@Interleave(group=TestVolatileCounter.class,threadCount=2)
	public void addOne() {
		i++;
	}
	@After
	public void checkResult() {
		assertEquals(2,i);
	}
}

The class TestVolatileCounter has one Junit test method, the method testCounter. This method executes the method addOne twice through an ExecutorService with a fixed thread size of two. The method addOne increments the variable i by one and the method checkResult checks that after the test run the variable i equals two.

The interleave annotation at the method addOne tells vmlens that you want to test all thread interleavings for this method. The group field let you group multiple methods together. In our case, we want to test addOne running in parallel with itself so only the method addOne is in the group TestVolatileCounter.class. The field testCount tells vmlens how many threads are executing the method. In our case, the method addOne is executed by the two threads of the ExecutorService so the field threadCount is two.

If you run the test with vmlens, vmlens reruns the test till all thread interleavings are tested or an error occurred. In our case, since the increment operation ++ is not atomic there are interleavings in which the variable i is one, not two. So the test stops with an error and vmlens shows in the "vmlens Explorer" view the executed statements:

Download the interleave annotation

The source code for the interleave annotation is in the github repository vmlens/annotation. You can download the annotation.jar file from maven central or as maven dependency:

<dependency>
  <groupId>com.vmlens</groupId>
  <artifactId>annotation</artifactId>
  <version>1.0.1</version>
</dependency>

Eclipse References

Run

vmlens provides two types of run configurations, one to run Junit tests and one to run all other types of applications:

Junit tests

To run Junit tests you can use the vmlens launch shortcut as shown below:

How to configure a Junit test run is described here.

All applications

To run vmlens with another type of application, create a "vmlens All Applications" run configuration. Select Run -> Run Configurations... from the main menu. And create a "vmlens All Applications" run configuration:

After you created your run configuration press run. After pressing run vmlens shows you the following dialog:

To run vmlens with an application on your local machine either inside or outside of eclipse add the vmlens agent string to the VM arguments of your application. To run on a remote machine export the agent files to a folder by pressing the export button.

Running on a remote machine

Copy this folder to your remote machine and configure your application with an agent string pointing to the agent.jar in this folder:

-javaagent:<Path of agent.jar>/agent.jar

When you start your application the vmlens agent creates a folder vmlens in the working directory of your application. After you stopped your application the agent stops and you can import the folder vmlens in eclipse:

Import vmlens folder in eclipse

Import the vmlens folder in eclipse. Select File -> Import... from the main menu and select the vmlens Agent files wizard as shown below:

Now vmlens will analyze the execution trace of your application and open the vmlens perspective in eclipse showing you the results.

Please set the java heap size for eclipse in the eclipse.ini to a high enough value, for example -Xmx5g

Changing the path of the vmlens folder

In the default configuration, the agent writes the execution trace in a folder called vmlens in the working directory of your application. To change this path, change the property eventDir in the file called run.properties in the folder which contains the agent.jar file. In the default configuration, this property is set to ./vmlens/

eventDir=./vmlens/

Run Configuration

The eclipse run configuration is shown below:

In the run configuration you can configure these properties:

mode
The mode let you select one of the three run modes: interleave, state or monitor. Those modes are described in detail here.
trace
Add method or method pattern to the list. When at least one pattern is in this list vmlens traces only inside this method.
do not trace
vmlens do not trace when inside one of the methods in the list.

Maven References

Config

An example for a vmlens plugin configuration is shown below:

<project>
     ...  
<build>
  <plugins>
    <plugin>
    <groupId>com.vmlens</groupId>
    <artifactId>interleave</artifactId>
    <version>1.0.1</version>
    <executions>
      <execution>
        <goals>
          <goal>test</goal>
        </goals>
      </execution>
    </executions>
    <configuration>
		<trace>
			<method>com.vmlens.test.issue.**</method>
		</trace>
		<doNotTrace>
			<method>com.vmlens.test.issue.TestRaceAggregating.**</method>
		</doNotTrace>	
	</configuration>
    </plugin>
     ...
    </plugins>
</build>
      ...
</project>

You can configure the following values:

trace
Add method or method pattern to the list. When at least one pattern is in this list vmlens traces only inside this method.
doNotTrace
vmlens do not trace when inside one of the methods in the list.

Eclipse run modes and maven plugins

vmlens provides the following three eclipse run modes or maven plugins:

interleave
The default mode. In this mode, vmlens traces monitor and memory accesses. vmlens detects data races and deadlocks.
monitor
In this mode, vmlens traces monitor accesses.
state
In this mode, vmlens traces memory accesses.