Documentation for Java Run Time Deadlock
Detection Agent
Authored By : Steve Sennebogen Niyaz Ahmed Amanullah Kevin Grant Sarath Kumar Subramanian Michael Salata
Course : CS 442 – Software Engineering II Group : A Date : November 23, 2011
1
Table of Contents
1. System Requirements ...... 4 1.1 PC Hardware……………………………………………………………...... 4 2. Installation Requirements ...... 5 2.1 Java Run Time Environment ...... 5 2.2. Download JAVA Runtime Deadlock Detection Agent…………………...7
3 . Supported Functionality………………………………………………………8 4. Graphical User Interface……………………………………………………....8 4.1 Overview …………………………………………………………………….8 4.2 Tabs…………………………………………………………………………..9 4.3 Thread Information…………………………………………………………9 4.4 File Menu…………………………………………………………………...10 4.5 Help………………………………………………………………………...11 5. Missing Functionality & Known Defects…………………………………….12
6 Trouble Shooting…………………………………………………………...... 13 6.1. Java Runtime Environment (JRE) Not Installed…………………………....13 6.2. Incorrect Java Program Path (or) Java Program Not Compiled………….....14 6.3.Incorrect Agent Library Name……………………………………………....14 6.4.Incorrect Syntax of Command to Run the Agent……………………………15
2
License
The MIT License (MIT) Copyright (c) 2011 Group A, CS442 Fall 2011. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sub- license, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
3
1.System Requirements The Java Run Time Deadlock Monitoring Agent performs best on systems with faster processors and more memory.
1.1 PC Hardware
Standard x86-compatible or x86-64-compatible personal computer
733MHz or faster CPU minimum
Compatible processors include: Intel: Celeron, Pentium II, Pentium III, Pentium 4, Pentium M, Xeon, and Core 2 processors AMD: Athlon, Athlon MP, Athlon XP, Athlon 64, Duron, Opteron, Turion 64 AMD Sempron
Multiprocessor systems supported
64-bit systems supported: ● AMD Athlon 64 ● AMD Opteron ● AMD Turion 64 ● AMD Sempron, 64-bit-capable ● Intel Pentium 4 and Core 2 processors
Memory 256MB minimum (512MB is recommended)
Display 16-bit or 32-bit display adapter is recommended
Disk Drives Hard Disk: At least 1GB free disk space recommended
Operating Systems JRT Deadlock Monitoring is available for both Windows and Linux operating systems
Windows Operating Systems ● Windows Vista ● Windows Server 2003 ● Windows Server 2008 ● Windows XP ● Windows 7
4
Linux Operating Systems ● Mandriva Linux 2006 and 2007 ● Red Hat Enterprise Linux 4.0 and newer ● Red Hat Linux 7.0 and newer ● SUSE Linux 8.2 and newer ● Ubuntu Linux 5.04 and newer
2 . Installation Instructions 2.1. Java Runtime Environment (JRE) Download the latest Java Runtime Environment, or JRE for Windows x64 from the link below. The Deadlock Detection Agent supports JAVA JRE version 6 or higher. http://www.oracle.com/technetwork/java/javase/downloads/jre-6u25-download-346243.html
JRE Installation Instructions
Step 1: Find the JRE installation file and open it.
Figure 1 of Section 2
5
Step 2: If you wish to change the destination folder check the “Change destination folder” box and click install
Figure 2 of Section 2
Step 3: Installing Files
Figure 3 of Section 2
6
Step 4: Installation Complete
Figure 4 of Section 2
Make sure the JAVA_HOME path is set. setx JAVA_HOME "PATH_TO_YOUR_JAVA_FOLDER\Java\jdk1.7.0_01"
2.2. Download JAVA Runtime Deadlock Detection Agent
Download the latest Deadlock Detection Agent Release 1.0 from our website: http://code.google.com/p/jrt-dma/downloads/list (Download the DDAgent.zip file)
Note: You need a self-extractor to extract the zip file. Download 7-Zip from: http://www.7-zip.org/download.html
You will find the DDAgent.dll (Dynamic-link library file), which you will use it with your JAVA program to run the product.
7
3 . Supported Functionality The Java Run Time Deadlock Monitoring Agent is intended to monitor the Java Virtual Machine for Thread Behavior, Object Locks, Stack Traces until a deadlock is detected. The Agent is intended to report the Java Developer the Threads that are involved in the deadlock along with Stack Traces and Object locks allocations for the deadlocked threads in a Graphical User Interface.
How to Use the Software? 1. The Java Run Time Deadlock Monitoring Agent is downloaded to the local directory. 2. The Java Application to be monitored is run in parallel with the Agent with the following command
java -agentpath:/pathTo/DDAgent.dll JavaProgram
3. On executing the above command if any deadlock is detected the Graphical User Interface Pops up with the Threads involved in Deadlock along with the object lock allocations of the corresponding threads are displayed.
4 . Graphical User Interface
4.1 Overview This is the user interface for the Deadlock Detection Agent for the Java Runtime Environment. First and foremost, this agent is for displaying information to the user in a clean and easily understandable format.
8
Figure 1 of Section 4
4.2 Tabs The tabs going across the top of the screen correspond to the program threads that the JRE is running. Users are able click the tabs to bring up the information panels corresponding to that thread.
4.3 Thread Information There are information boxes in each threads tab. These boxes provide information on which the current tab’s thread is dependent on, the stack trace of the current thread, and each object to which the thread is synchronized.
9
. Figure 2 of Section 4
4.4 File Menu Exit: Once clicked closes the deadlock detection agent. (Alpha: Currently does not have functionality) AddTab (Alpha): Currently tests the functionality to add tabs to the user interface. These tabs are named by default “NewTab” Test (Alpha): Currently tests the functionality to remove tabs. Removes tabs of the name “NewTab”. This corresponds with AddTab functionality.
10
File Menu Screen Shot (Alpha)
Figure 3 of Section 4
File Menu Screen Shot
Figure 4 of Section 4
4.5 Help About: Once clicked, pops up a message box with information about the creators of the Deadlock Detection Agent.
Figure 5 of Section 4
Figure 6 of Section 4
11
5 . Missing Functionality & Known Defects The DDAgent System does not successfully detect deadlock.
Explanation: At the insistence of the client, DDAgent relies on JVMTI to interact with the java virtual machine. The overall deadlock detection design was to build a directed Graph of Java Threads where a waiting thread has a directed edge to a owning thread for a given monitor.
Two methods were utilized to attempt to collect enough information from the JVM. Given the documentation for the JVMTI, there was no expectation for problems with the implementation.
Method 1: Using the JVMTI, register a callback on thread entering a monitor. On entering a monitor: 1: DDAgent enumerate all threads, then 2: Collects a list of: a: owned monitors, that is monitors a given thread had a lock on b: contended monitor, that is, the monitor, if any, the thread was waiting for. The intent was to build a digraph from this information. Upon execution of this method, The JVMTI would report that the same monitor was owned by 2 threads. This should not be a possible state for the Java Virtual Machine to be in.
Method 2: Using the JVMTI, register a callback on a thread entering a monitor On entering a monitor: 1: DDAgent enumerates all monitors a: Fetch the owning thread for each monitor b: Fetch a list of waiting threads for each monitor.
The intent was to build a digraph from this information. Upon execution, the JVMTI did not show any cyclic thread waiting when a Deadlock was clearly present in the sample program. That is, There was no Thread A waiting on Thread B waiting on Thread A. Without a way to get accurate information about the state of the JVM from the JVMTI, there was no way for this project to complete successfully.
12
6 . Trouble Shooting
6. 1. JAVA RUNTIME ENVIRONMENT (JRE) NOT INSTALLED
ERROR: 'javac' is not recognized as an internal or external command, operable program or batch file.
Figure 1 of Section 6
REASON: ● JAVA Runtime Environment is not installed. ● JAVA_HOME path is not set
SOLUTION: ● Make sure JRE is installed correctly, if not follow the instructions in section 1. a for installing JRE ● Verify in system environment variables whether the JAVA_HOME path is set. If not set the JAVA_HOME path as: “setx JAVA_HOME "PATH_TO_YOUR_JAVA_FOLDER\Java\jdk1.7.0_01" in the Command Prompt.
13
6.2. INCORRECT JAVA PROGRAM PATH (or) JAVA PROGRAM NOT COMPILED.
ERROR: Error: Could not find main class
Figure 2 of Section 6
REASON: ● Incorrect path to the user Java program ● Typo in the Java program name. ● Java program not compiled by user (class file not generated)
SOLUTION: ● Ensure if correct path to the Java program is given ● Check for the user Java program name.
6. 3. INCORRECT AGENT LIBRARY NAME
ERROR: Error occurred during initialization of VM Could not find agent library DDAAgent.dll in absolute path, with error: Can't find dependent libraries
14
Figure 3 of Section 6
REASON: ● The Agent name is incorrectly typed (DDAgent.dll)
SOLUTION: ● Make sure the agent name is specified correctly and check for the path of the agent library.
6. 4. INCORRECT SYNTAX OF THE COMMAND TO RUN THE AGENT
ERROR: Unrecognized option: -agenttpath:DDAgent.dll Error: Could not create the Java Virtual Machine. Error: A fatal exception has occurred. Program will exit. (or) javac: invalid flag: -agentpath:DDAgent.dll Usage: javac
15
Figure 4 of Section 6
Figure 5 of Section 6
REASON: ● The command to run the agent is syntactically incorrect
SOLUTION: ● Verify the command to run the Agent. The Java Application to be monitored is run in parallel with the Agent with the following command
java -agentpath:/pathTo/DDAgent.dll JavaProgram
16