Debugging Multi-threaded Applications in NetBeans IDE

This tutorial needs a review. You can edit it in GitHub following these contribution guidelines.

This document describes how to use the Debugging window in NetBeans IDE to debug multi-threaded applications. The tutorial also demonstrate how to use the IDE to detect deadlocks in an application.

The Debugging window simplifies the debugging process by integrating into one window the information about debugging sessions, application threads and thread call stacks. The Debugging window enables you to easily see the status of application threads and suspend and resume any of the threads in the session.

This tutorial uses two sample projects to demonstrate how to work with the Debugging window. To complete this tutorial you first download and open the projects Gallery and Deadlock.

To follow this tutorial, you need the Gallery Project and Deadlock Project.

Downloading the Sample Projects

You can download the sample projects used in this tutorial in the following ways.

  • Download a zip archive of the finished project.

  • Checkout the project sources from the NetBeans Samples by performing the following steps:

    1. Choose Team > Subversion > Checkout from the main menu.

    2. In the Checkout dialog box, enter the following Repository URL: https://svn.netbeans.org/svn/samples~samples-source-code Click Next.

      1. Click Browse to open the Browse Repository Folders dialog box.

      2. Expand the root node and select samples/java/debugging-samples. Click OK.

      3. Specify the Local Folder for the sources (the local folder must be empty).

      4. Click Finish.

When you click Finish, the IDE initializes the local folder as a Subversion repository and checks out the project sources.

  1. Click Open Project in the dialog that appears when checkout is complete.

Note. For more about checking out sources with Subversion, see the section on Setting up Subversion in the Guide to Subversion in NetBeans IDE.

Opening the Projects

In this tutorial you will use two applications to demonstrate the IDE’s support for debugging multi-threaded applications. In this exercise you will open and then run the two projects in the IDE. After you run the projects you will then proceed to debug each of the projects.

Running the Gallery Project

The Gallery application is a simple Java Swing application that plays animated images. The application has two buttons that enable you to add and remove animated images. In this exercise you run the Gallery application.

  1. Download and expand the + debugging-samples.zip + archive to your local system.

  2. Choose File > Open from the main menu.

  3. Locate and select the Gallery project in the debugging-samples directory. Click Open.

When you click Open the IDE opens and displays the project in the Projects window. If you expand the project node in the Projects window you can see that the project is a simple Java Swing application.

  1. Right-click the project node and choosing Run to launch the Gallery application.

  2. In the Gallery application, click 'More' to add images and click 'Less' to remove images.

debugging gallery app
Figure 1. Gallery application

  1. Close the Gallery application window.

The Gallery project is a simple multi-threaded application that you will debug in this tutorial.

Running the Deadlock Project

The Deadlock application contains a main method that starts a thread that runs for 500000 milliseconds. The main method starts two threads that print to the Output window when they finish.

  1. Choose File > Open from the main menu.

  2. Locate and select the Deadlock project in the debugging-samples directory. Click Open.

When you click Open the IDE opens and displays the project in the Projects window. If you expand the project node in the Projects window you can see that the project is a simple Java application.

  1. Right-click the project node and choosing Run to launch the Deadlock application.

When you click Run, the Output window opens and displays the following output.

run:
Application started
MyThread2 successfully finished.
MyThread1 successfully finished

  1. Allow the application to end normally (five minutes).

When the Deadlock application ends you will see the following in the Output window.

Main thread finished

The Deadlock project is a simple Java application with two threads. When you debug the application you will create a deadlock to illustrate how the IDE can help you detect deadlocks.

Debugging the Sample Projects

The Gallery project is a simple Java Swing application that displays animated images. You add and remove the images by clicking buttons in the application. Clicking the 'More' button starts a new thread that displays and animates an image. Clicking the 'Less' button stops the most recent thread, stopping the animation and removing the image.

Suspending Threads

In this exercise you start debugging the Gallery application and add some images to start some application threads. When you start a debugging session the IDE opens the Debugging window in the left pane of the IDE. The Debugging window displays a list of the threads in the session.

  1. Right-click the Gallery project in the Projects window and choose Debug.

When you click Debug, the IDE starts the Gallery application and opens the default debugging windows. The IDE automatically opens the Debugging window in the left side of the main window and opens the Debugger Console in the Output window.

  1. Click 'More' three times in the Gallery application to start three threads displaying animated images.

If you look in the Debugging window you can see that a new thread was started for each animation.

debugging start
Figure 2. Debugging window

  1. Suspend two of the threads by clicking the 'Suspend thread' button to the right of the thread in the Debugging window.

When a thread is suspended, the icon for the thread changes to indicate the new state. You can expand the thread node to view the thread’s call stack. You can right-click items in the Debugging window to open a pop-up menu with debug commands.

debugging start suspend
Figure 3. Debugging window with two suspended threads

If you look at the Gallery application you can see that when you suspended the threads the animation for those threads stopped.

The Debugging window enables you to quickly view and change the status of threads in the session. By default the Debugging window displays the Resume and Suspend buttons in the right side of the window. You can hide the buttons and further customize the display of the Debugging window by using the toolbar at the bottom of the Debugging window. If you are running multiple debugging sessions you can use the drop down list at the top of the Debugging window to choose which session is displayed in the window.

debugging window toolbar
Figure 4. Debugging window toolbar

Switching Threads

This exercise demonstrates what happens when you are stepping through an application and a different application thread hits a breakpoint. In this exercise you will set a method breakpoint and start stepping through the application. While you are stepping through the application you will start a new thread that will also hit the breakpoint. The IDE informs you when this occurs by displaying a notification in the Debugging window. You will then switch between threads.

  1. In the Gallery application window, click 'Less' or 'More' until only two or three of the animations are displayed in the window.

  2. In the Projects window of the IDE, expand the gallery package and double-click Gallery.java to open the file in the editor.

  3. Insert a method breakpoint in Gallery.java at the beginning of the run method by clicking in the left margin at line 175.

  4. Click 'More' in the Gallery application to start a new thread that will hit the method breakpoint.

  5. Click Step Over (F8) and start stepping through the method until the Program Counter reaches line 191.

You can see that the Program Counter in the margin of the editor indicates your position as you step through the method.

  1. Click 'More' in the Gallery application to start a new thread that will hit the method breakpoint.

When the new thread hits the method breakpoint a New Breakpoint Hit notification appears in the Debugging window that informs you that another thread hit a breakpoint while you were stepping through the method.

debugging newbreakpointhit
Figure 5. New Breakpoint Hit notification

When you are stepping through a thread and a breakpoint is hit in another thread, the IDE gives you the option to switch to the other thread or continue stepping through the current thread. You can click the arrow button in the New Breakpoint Hit notification to switch to the thread that encountered the breakpoint. You can switch to the new thread at any time by selecting the thread in the notice window. Stepping through the current breakpoint thread resumes the current thread but the status of other application threads remains unchanged.

Note. If you look in the Debugging window you can see that the current thread (Thread_Jirka) is indicated by a green bar in the margin. The thread that invoked the notification by hitting the breakpoint (Thread_Roman) is indicated by a yellow bar and the thread icon indicates that the thread is suspended by a breakpoint.

debugging current suspended
Figure 6. New Breakpoint Hit notification

  1. Click the arrow in the New Breakpoint Hit notification to switch the current thread to the new thread (Thread_Roman).

When you switch to the new thread you can see the following:

  • The program counter moves to the position at line 175 in the new current thread (Thread_Roman).

  • A 'suspended thread' annotation is now visible in the margin at line 191 indicating that a thread (Thread_Jirka) is suspended at that line.

debugging editor suspendedannot
Figure 7. Editor showing debugging annotations

  1. Click Step Over a few times to step through the new current thread (Thread_Roman).

  2. Right-click the 'suspended thread' annotation in the editor margin and choose Set as Current Thread > Thread_Jirka to switch back to the suspended thread.

debugging editor setcurrent
Figure 8. Editor showing Set as Current Thread pop-up

Alternatively, you can invoke the Current Thread Chooser (Alt+Shift+T; Ctrl+Shift+T on Mac) and switch to any of the application threads.

debugging thread chooser
Figure 9. Gallery application

When you switch back to Thread_Jirka, the suspended thread annotation appears next to the line where Thread_Roman was suspended. You can resume Thread_Roman by clicking Resume in the Debugging window.

debugging editor suspendedannot2
Figure 10. Editor showing debugging annotations

The Debugging window enables you to very precisely view and control thread states. The debugger manages application threads to simplify the debugging workflow and to prevent the debugging process from creating deadlocks. In this exercise you saw the following behavior when debugging an application in the IDE.

  • When a thread hits a breakpoint only the breakpoint thread is suspended.

  • When stepping through the application, the current thread is not affected when other application threads hit breakpoints.

  • Stepping only resumes the current thread. When the step is completed only the current thread is suspended.

You can quit the Gallery application. In the next exercise you will debug the Deadlock application and use the IDE to help you detect a deadlock.

Detecting Deadlocks

The IDE can help you identify potential deadlock situations by automatically searching for deadlocks among all suspended threads. When a deadlock is detected, the IDE displays a notification in the Debugging window and identifies the involved threads.

To demonstrate the IDE’s deadlock detection, you will run the sample Deadlock project in the debugger and create a deadlock situation.

  1. Expand the myapplication package and open Thread1.java and Thread2.java in the source editor.

  2. Set a breakpoint in Thread1.java at line 20 and in Thread2.java at line 20

To set the breakpoint, click in the margin of the source editor next to the line where you want to set the breakpoint. The breakpoint annotation appears in the left margin next to the line. If you open the Breakpoints window (Alt-Shift-5; Ctrl+Shift+5 on Mac) you can see that the two breakpoints are set and enabled.

debug deadlock setbkpt
Figure 11. Editor showing breakpoint set at line 20

  1. Right-click the Deadlock project in the Projects window and choose Debug.

The main method will run the two threads, and both threads will be suspended at one of the breakpoints. You can see the threads suspended by the breakpoints in the Debugging window.

  1. In the Debugging Window, resume the suspended threads ( MyThread1 and MyThread2 ) by clicking the Resume buttons to the right of the suspended threads in the Debugging window.

debug deadlock resume
Figure 12. Resuming suspended threads in the Debugging window

Resuming the threads MyThread1 and MyThread2 will create the deadlock state.

  1. Choose Debug\Check for Deadlock from the main menu to check the suspended threads for deadlocks.

debug deadlock detected
Figure 13. Resuming suspended threads in the Debugging window

If you check the application for deadlocks and a deadlock is detected, a message appears in the Debugging Window informing you about the deadlock. You can see that the threads in deadlock are indicated with a red bar in the left margin of the Debugging window.

This tutorial was a basic introduction to some of the debugging features in the IDE. The Debugging window enables you to easily suspend and resume threads when debugging an application. This can be extremely helpful when you are debugging multi-threaded applications.