How to report a deadlock
Say you've encountered a problem in Eclipse that has one of the following symptoms:
- A long pause where the GUI does not redraw or respond
- A deadlock or freeze where the GUI stops responding indefinitely
- CPU pegged at 100% indefinitely
- A modal dialog that won't close
- What build of Eclipse you are using (see Help > About)
- What VM you are using (version and vendor). Use "java -version" to find out version information.
- What you were doing at the time of the deadlock (what dialog, wizard, editor, etc)
- Whether it is reproducible; if so, provide steps
- Once the bug report is created, attach a stack trace using the "Create a New Attachment" link in bugzilla.
If you are running on a Sun VM, the stack trace is typically just printed directly on the console. In this case, paste the contents into a file and then attach the file. Stack traces pasted directly into bugzilla look very ugly. On an IBM VM, the stack trace is written to a file in the working directory of the Java process. Typically this will be found in the eclipse install directory. The steps for producing a stack trace vary according to what operating system you are using:
Getting a stack trace on Windows
Using the Java StackTrace tool
This is the preferred method, since its output is most verbose and it's most easily applied. Given that your Eclipse is currently hanging in a deadlock, best use the tool found at the adaptj home page, since it requires no preparations:
- Follow the link and select button "Launch" (press "OK" to "Run as a Java WebStart Application")
- Select menu Process > Select
- In the combo box "Process ID" press the "..." button, select "eclipse.exe" application and click OK
- Pick menu Process > Thread Dump
- File > Save As (enter some name e.g. C:\myThreadDump.txt)
Attach that file on bugzilla when filing a bug that describes how you got the deadlock.
Using eclipse -consolelog
As an alternative, if you are interested in reporting bugs, it is useful to always run with a console open so you can obtain stack traces. If you are using Eclipse 3.3 (Europa) or greater on Windows, you can simply run with eclipsec.exe to obtain a console window. On Eclipse 3.2 or older, you will need to specify java.exe as your VM on the command line. Here is a typical command line for starting Eclipse using java.exe:
eclipse -vm c:\jre\bin\java.exe -vmargs -Xmx300M
Or, if you normally use your system's default java VM, you can use
eclipse -consolelog -debug
Once you have a Java console window, you can obtain a stack trace by simply hitting Ctrl+Break when the console window is active.
Note: its recommended you increase the "buffering size" of the console window, to a wide width such as 300 (default is usually 80) and perhaps even a long length (such as 3000) so there's plenty of room for a well formatted stack trace. Then, preferably, copy/paste the stack trace to a text file and attach it to a bugzilla, so its formatting is preserved.
Debugging as an Eclipse Application
The same is possible if you start Eclipse using the "Eclipse Application" launch configuration (ie. from another instance of Eclipse). The problem here is that you don't have a console in which to press Ctrl+Break. You will need a tool like [SendSignal].
SendSignal can send a break to any process and you will get the stack dump in the Eclipse console of the controlling instance. This has the additional advantage that the buffer will probably be big enough. The tool needs the PID (process id) which is not that simple to find on Windows. Either you use a tool like [Process Explorer]. There, you can see the right process as a child of your Eclipse process.
If you can't do this, you'll have to use the Windows Task Manager. The first step is to make the PID visible. Select the "Process" tab and then "Select columns..." in the View menu. Make sure PID is selected. To determine which PID is the one you're looking for, sort the processes by name and watch the running Java processes (javaw.exe). Look again after you started the Eclipse process. There should be a new process, now.
Note: It doesn't do much harm if you send the signal to the wrong, process. You just won't see the thread dump.
Using jconsole (requires JDK 1.5 or later)
This works on any OS:
- Launch eclipse -vmargs -Dcom.sun.management.jmxremote
- Launch the JDK's jconsole tool from commandline. You can attach to the Java Process and copy&paste the thread dump.
Using jps / jstack (requires JDK 1.6 or later)
- On commandline, use jps to find the PIDs of Java processes and jstack to show the stack trace of Java processes: jstack pid
- Supported starting JDK 5 for UNIX / JDK 6 for Windows
- See this Weblog on jstack
Getting a stack trace on other platforms
On all Unix-based platforms, the steps for producing a stack dump are the same:
- Use the "ps" command to find out the process id (pid) of the Java VM
- Invoke "kill -3 <pid>" where <pid> is the process id of the Java VM
A thread dump will be printed on the console where you started Eclipse. Since it may be long, in order to Copy & Paste it, it might be necessary to scroll and/or reduce the font size (xterm: right-click > font size > unreadable).
For yet other options to get a thread dump, see Mylyn Contributor Reference#Debugging
For diagnosing and getting stack traces for deadlocks using the Eclipse debugger see Deadlock detection with Eclipse