Friday, December 31, 2010

Running Freescale’s Deadlock Preventer from the command line

One of the best ways to detect potential deadlocks is to integrate the Deadlock Preventer in a release engineering process, so it can run with the java program executing the automated tests, and have an excellent code coverage to analyze the system’s synchronization primitives.

To integrate the Deadlock Preventer in a release engineering process, although, means being able to configure the test scripts to run the Deadlock Preventer.

Adding the Deadlock preventer is as simple as adding the following two arguments to the “java” executable:

-javaagent:path-to\com.freescale.deadlockPreventer.wrapper_1.0.0\com.freescale.deadlockpreventer.jar

-Xbootclasspath/a:path-to\com.freescale.deadlockPreventer.wrapper_1.0.0\com.freescale.deadlockpreventer.jar;path-to\javassist.wrapper_1.0.0\javassist.jar

Where the two plugins “com.freescale.deadlockPreventer.wrapper” and “javassist.wrapper” can be obtained from the following link(in the build/eclipse/plugins sub-folder):

https://github.com/sbeauchamp/Deadlock-Preventer/zipball/master

The following java property can be specified to write the Deadlock Preventer output to a file:

-Dcom.freescale.deadlockpreventer.logToFile=path-to\deadlock_preventer_output.log

Alternatively, the output can be re-directed to the standard output with the following property:

-Dcom.freescale.deadlockpreventer.logToStream=out

or

-Dcom.freescale.deadlockpreventer.logToStream=err

Memory Requirements

An important factor to keep in mind, is that running a java program with the Deadlock Preventer will cause all locks ever acquired to be referenced in memory by the analysis engine, so they will not be garbage collected for the life time of the program.

This can cause some significant memory consumption increase, and may require the –Xmx flag to be passed to java to be increased.

For example, running an eclipse.exe instance with the the Deadlock Preventer can increase its memory usage by several hundred MBs.

Running the Deadlock Preventer interactively

Another alternative to either running the Deadlock Preventer in the Eclipse workbench with the UI or running it in an automated build, is to use the built-in command line server/client.

To start the server, the following command can be used:

java –cp path-to\com.freescale.deadlockPreventer.wrapper_1.0.0\com.freescale.deadlockpreventer.jar com.freescale.deadlockpreventer.ConsoleNetworkServer 43537

The last argument is the port number of the server, which can be omitted, in which case the default port will be used, 43537.

The following output will then appear to the command line:

Server started on port: 43537
services:
  report: report.2
  query: query.1
Type 'help' for a list of commands.

This information can then be used to pass the following two properties to the java instance that is running the Deadlock Preventer (the one that is getting the –javagent flag):

-Dcom.freescale.deadlockpreventer.reportService=localhost:43537:report.2

-Dcom.freescale.deadlockpreventer.queryService=localhost:43537:query.1

Note that if the server is started on a different machine, the “localhost” string must be replaced by the IP address of the server.

When the Deadlock Preventer is connected to the server, any inconsistent locking detected will be displayed on the server’s console interactively, so that the user can decide to continue, or abort the program.  The server console can also be used to query lock statistics with the following commands:

getLockCount

      Returns the number of locks in the program.
getDetails index end

      Return detailed information on the lock(s) from index to end (being numbers between 0 and the number of locks in the program)
getAll

      Return all lock information as output on the standard out stream
writeAll file-path

      Download all lock information and write the complete output in a file

Note that downloading lock statistics can require quite a lot of memory and bandwidth (several hundred MBs for an eclipse workbench, for example).

4 comments:

jtonic said...

Wow. Good news about Deadlock Preventer.
Could the deadlock preventer be used in a plain (Equinox) OSGi application, using, say, custom OSGi commands (CommandProvider - http://eclipsesource.com/blogs/2008/08/01/tip-custom-osgi-equinox-console-commands/)?
I like the client/server approach, can deadlock statistics be queried using JMX (JConsole)?

Regards

Serge Beauchamp said...

That's a interesting suggestion, I'll look into hooking it up to osgi and JMX, thanks!

Paul said...

I went to the eclipsecon talk and was very impressed. Good work on the software, and fantastic slides too.

Serge Beauchamp said...

Thanks, I appreciate :)