| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <title>Debugging Multi-threaded Applications in NetBeans IDE</title> |
| <link rel="stylesheet" href="../../../netbeans.css"> |
| <meta name="description" content="An guide to using the debugger in NetBeans IDE to debug a multi-threaded application."/> |
| </head> |
| <body> |
| <h1>Debugging Multi-threaded Applications in NetBeans IDE</h1> |
| |
| <p>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.</p> |
| <p>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. |
| </p> |
| |
| <p>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. |
| </p> |
| <p class="tips">Watch the <a href="debug-multithreaded-screencast.html">Video of Debugging a Multi-threaded Application in NetBeans IDE</a>.</p> |
| |
| <p><b>Contents</b></p> |
| <img src="../../../images_www/articles/73/netbeans-stamp-80-74-73.png" class="stamp" alt="Content on this page applies to NetBeans IDE 7.2, 7.3, 7.4 and 8.0" title="Content on this page applies to the NetBeans IDE 7.2, 7.3, 7.4 and 8.0" > |
| <ul> |
| <li><a href="#Exercise_00">Downloading the Sample Projects</a> |
| <li><a href="#Exercise_10">Opening the Sample Projects</a> |
| <ul> |
| <li><a href="#Exercise_11">Running the Gallery Project</a></li> |
| <li><a href="#Exercise_12">Running the Deadlock Project</a></li> |
| </ul> |
| </li> |
| <li><a href="#Exercise_20">Debugging the Sample Projects</a> |
| <ul> |
| <li><a href="#Exercise_21">Suspending Threads</a></li> |
| <li><a href="#Exercise_22">Switching Threads</a></li> |
| <li><a href="#Exercise_23">Detecting Deadlocks</a></li> |
| </ul> |
| |
| |
| </li> |
| |
| </ul> |
| |
| <p><b>To follow this tutorial, you need the following software and resources.</b></p> |
| <table> |
| <tr> |
| <th class="tblheader" scope="col">Software or Resource</th> |
| <th class="tblheader" scope="col">Version Required</th> |
| </tr> |
| <tr> |
| <td class="tbltd1"><a href="https://netbeans.org/downloads/index.html">NetBeans IDE</a></td> |
| <td class="tbltd1">7.2, 7.3, 7.4, 8.0</td> |
| </tr> |
| <tr> |
| <td class="tbltd1"><a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Java Development Kit (JDK)</a></td> |
| <td class="tbltd1">version 7 or 8</td> |
| </tr> |
| <tr> |
| <td class="tbltd1"><a href="https://netbeans.org/projects/samples/downloads/download/Samples/Java/debugging-samples.zip">Gallery Project and Deadlock Project</a></td> |
| <td class="tbltd1"> </td> |
| </tr> |
| </table> |
| |
| |
| <a name="Exercise_00"></a> |
| <h2>Downloading the Sample Projects</h2> |
| <p>You can download the sample projects used in this tutorial in the following ways.</p> |
| <ul> |
| <li>Download <a href="https://netbeans.org/projects/samples/downloads/download/Samples/Java/debugging-samples.zip">a zip archive of the finished project</a>.</li> |
| <li>Checkout the project sources from the NetBeans Samples by performing the following steps: |
| <ol> |
| <li>Choose Team > Subversion > Checkout from the main menu.</li> |
| <li>In the Checkout dialog box, enter the following Repository URL:<br/> |
| <tt>https://svn.netbeans.org/svn/samples~samples-source-code</tt><br/> |
| Click Next.</li> |
| <li>Click Browse to open the Browse Repository Folders dialog box.</li> |
| <li>Expand the root node and select <strong>samples/java/debugging-samples</strong>. Click OK.</li> |
| <li>Specify the Local Folder for the sources (the local folder must be empty).</li> |
| <li>Click Finish. |
| <p>When you click Finish, the IDE initializes the local folder as a Subversion repository |
| and checks out the project sources.</p> |
| </li> |
| <li>Click Open Project in the dialog that appears when checkout is complete.</li> |
| </ol> |
| |
| <p class="notes"><strong>Note.</strong> |
| For more about checking out sources with Subversion, |
| see the section on <a href="../ide/subversion.html#settingUp">Setting up Subversion</a> |
| in the <a href="../ide/subversion.html">Guide to Subversion in NetBeans IDE</a>.</p> |
| </li> |
| </ul> |
| |
| |
| |
| <!-- ===================================================================================== --> |
| <a name="Exercise_10"></a> |
| <h2>Opening the Projects</h2> |
| <p>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.</p> |
| |
| <div class="indent"> |
| |
| <a name="Exercise_11"></a> |
| <h3>Running the Gallery Project</h3> |
| <p>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.</p> |
| <ol> |
| <li>Download and expand the <a href="https://netbeans.org/projects/samples/downloads/download/Samples/Java/debugging-samples.zip"><tt>debugging-samples.zip</tt></a> archive to your local system.</li> |
| <li>Choose File > Open from the main menu.</li> |
| <li>Locate and select the Gallery project in the debugging-samples directory. Click Open. |
| <p>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.</p></li> |
| <li>Right-click the project node and choosing Run to launch the Gallery application.</li> |
| <li>In the Gallery application, click 'More' to add images and click 'Less' to remove images.<br /> |
| <img src="../../../images_www/articles/72/java/debug-multithread/debugging-gallery-app.png" alt="Screenshot of Gallery application" title="Gallery application" class="margin-around b-all" /> |
| </li> |
| <li>Close the Gallery application window.</li> |
| </ol> |
| <p>The Gallery project is a simple multi-threaded application that you will debug in this tutorial.</p> |
| <a name="Exercise_12"></a> |
| <h3>Running the Deadlock Project</h3> |
| <p>The Deadlock application contains a <tt>main</tt> method that starts a thread that runs for 500000 milliseconds. |
| The <tt>main</tt> method starts two threads that print to the Output window when they finish.</p> |
| |
| <ol> |
| <li>Choose File > Open from the main menu.</li> |
| <li>Locate and select the Deadlock project in the debugging-samples directory. Click Open. |
| <p>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.</p></li> |
| <li>Right-click the project node and choosing Run to launch the Deadlock application. |
| <p>When you click Run, the Output window opens and displays the following output.</p> |
| <pre class="examplecode">run: |
| Application started |
| MyThread2 successfully finished. |
| MyThread1 successfully finished</pre></li> |
| <li>Allow the application to end normally (five minutes). |
| <p>When the Deadlock application ends you will see the following in the Output window.</p> |
| <pre class="examplecode">Main thread finished</pre> |
| </li> |
| </ol> |
| <p>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.</p> |
| |
| </div> |
| |
| <!-- ===================================================================================== --> |
| <a name="Exercise_20"></a> |
| <h2>Debugging the Sample Projects</h2> |
| <p>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. |
| </p> |
| |
| <div class="indent"> |
| <a name="Exercise_21"></a> |
| <h3>Suspending Threads</h3> |
| <p>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.</p> |
| |
| <ol> |
| <li>Right-click the Gallery project in the Projects window and choose Debug. |
| <p>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.</p></li> |
| <li>Click 'More' three times in the Gallery application to start three threads displaying animated images. |
| <p>If you look in the Debugging window you can see that a new thread was started for each animation.</p> |
| <img src="../../../images_www/articles/72/java/debug-multithread/debugging-start.png" width="375" height="151" alt="Screenshot of Debugging window" title="Debugging window" class="margin-around b-all" /> |
| </li> |
| <li>Suspend two of the threads by clicking the 'Suspend thread' button to the right of the thread in the Debugging window. |
| <p> |
| 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.</p> |
| <img src="../../../images_www/articles/72/java/debug-multithread/debugging-start-suspend.png" width="375" height="151" alt="Screenshot of Debugging window with two suspended threads" title="Debugging window with two suspended threads" class="margin-around b-all" /> |
| <p>If you look at the Gallery application you can see that when you suspended the threads the animation for those threads stopped. </p></li> |
| </ol> |
| |
| <p>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.</p> |
| <img src="../../../images_www/articles/72/java/debug-multithread/debugging-window-toolbar.png" width="378" height="60" alt="Screenshot of Debugging window toolbar" title="Debugging window toolbar" class="margin-around b-all" /> |
| |
| <a name="Exercise_22"></a> |
| <h3>Switching Threads</h3> |
| <p>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.</p> |
| |
| <ol> |
| <li>In the Gallery application window, click 'Less' or 'More' until only two or three of |
| the animations are displayed in the window.</li> |
| <li>In the Projects window of the IDE, expand the <tt>gallery</tt> package and double-click <tt>Gallery.java</tt> |
| to open the file in the editor.</li> |
| <li>Insert a method breakpoint in <tt>Gallery.java</tt> at the beginning of the <tt>run</tt> method |
| by clicking in the left margin at line 175.</li> |
| <li>Click 'More' in the Gallery application to start a new thread that will hit the method breakpoint.</li> |
| <li>Click Step Over (F8) and start stepping through the method until the Program Counter reaches line 191. |
| <p>You can see that the Program Counter in the margin of the editor indicates your position as you step through the method.</p></li> |
| <li>Click 'More' in the Gallery application to start a new thread that will hit the method breakpoint. |
| <p>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.</p> |
| <img src="../../../images_www/articles/72/java/debug-multithread/debugging-newbreakpointhit.png" width="585" height="90" alt="Screenshot of New Breakpoint Hit notification" title="New Breakpoint Hit notification" class="margin-around b-all" /> |
| <p>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.</p> |
| |
| <p class="notes"><strong>Note.</strong> 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.</p> |
| <img src="../../../images_www/articles/72/java/debug-multithread/debugging-current-suspended.png" width="375" height="200" alt="Screenshot of New Breakpoint Hit notification" title="New Breakpoint Hit notification" class="margin-around b-all" /> |
| </li> |
| <li>Click the arrow in the New Breakpoint Hit notification to switch the current thread to the new thread (Thread_Roman). |
| <p>When you switch to the new thread you can see the following:</p> |
| <ul> |
| <li>The program counter moves to the position at line 175 in the new current thread (Thread_Roman).</li> |
| <li>A 'suspended thread' annotation is now visible in the margin at line 191 indicating that |
| a thread (Thread_Jirka) is suspended at that line.</li> |
| </ul> |
| <img src="../../../images_www/articles/72/java/debug-multithread/debugging-editor-suspendedannot.png" width="436" height="402" alt="Screenshot of editor showing debugging annotations" title="Editor showing debugging annotations" class="margin-around b-all" /> |
| </li> |
| <li>Click Step Over a few times to step through the new current thread (Thread_Roman).</li> |
| <li>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.<br/> |
| <img src="../../../images_www/articles/72/java/debug-multithread/debugging-editor-setcurrent.png" width="436" height="291" alt="Screenshot of editor showing Set as Current Thread pop-up" title="Editor showing Set as Current Thread pop-up" class="margin-around b-all" /> |
| <p class="tips">Alternatively, you can invoke the Current Thread Chooser (Alt+Shift+T; Ctrl+Shift+T on Mac) and switch to any |
| of the application threads.</p> |
| <img src="../../../images_www/articles/72/java/debug-multithread/debugging-thread-chooser.png" width="355" height="122" alt="Screenshot of Gallery application" title="Gallery application" class="margin-around b-all" /></li> |
| </ol> |
| <p>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.</p> |
| <img src="../../../images_www/articles/72/java/debug-multithread/debugging-editor-suspendedannot2.png" width="436" height="300" alt="Screenshot of editor showing debugging annotations" title="Editor showing debugging annotations" class="margin-around b-all" /> |
| |
| <p>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.</p> |
| <ul> |
| <li>When a thread hits a breakpoint only the breakpoint thread is suspended.</li> |
| <li>When stepping through the application, the current thread is not affected when other application threads hit breakpoints.</li> |
| <li>Stepping only resumes the current thread. When the step is completed only the current thread is suspended.</li> |
| </ul> |
| <p>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.</p> |
| |
| <a name="Exercise_23"></a> |
| <h3>Detecting Deadlocks</h3> |
| <p>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.</p> |
| |
| <p>To demonstrate the IDE's deadlock detection, you will run the sample Deadlock project in |
| the debugger and create a deadlock situation.</p> |
| |
| <ol> |
| <li>Expand the <tt>myapplication</tt> package and open <tt>Thread1.java</tt> and <tt>Thread2.java</tt> in the source editor.</li> |
| <li>Set a breakpoint in <tt>Thread1.java</tt> at line 20 and in <tt>Thread2.java</tt> at line 20 |
| <p>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.</p> |
| <img src="../../../images_www/articles/72/java/debug-multithread/debug-deadlock-setbkpt.png" width="589" height="373" alt="Screenshot of editor showing breakpoint set at line 20" title="Editor showing breakpoint set at line 20" class="margin-around b-all" /> |
| </li> |
| <li>Right-click the Deadlock project in the Projects window and choose Debug. |
| <p>The <tt>main</tt> 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.</p></li> |
| <li>In the Debugging Window, resume the suspended threads (<tt>MyThread1</tt> and <tt>MyThread2</tt>) by clicking the Resume buttons |
| to the right of the suspended threads in the Debugging window.<br /> |
| <img src="../../../images_www/articles/72/java/debug-multithread/debug-deadlock-resume.png" width="585" height="283" alt="Screenshot of resuming suspended threads in the Debugging window" title="Resuming suspended threads in the Debugging window" class="margin-around b-all" /> |
| <p>Resuming the threads <tt>MyThread1</tt> and <tt>MyThread2</tt> will create the deadlock state.</p> |
| <li>Choose Debug\Check for Deadlock from the main menu to |
| check the suspended threads for deadlocks.<br /> |
| <img src="../../../images_www/articles/72/java/debug-multithread/debug-deadlock-detected.png" width="372" height="308" alt="Screenshot of resuming suspended threads in the Debugging window" title="Resuming suspended threads in the Debugging window" class="margin-around b-all" /> |
| <p>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.</p> |
| </li> |
| </ol> |
| |
| |
| </div> |
| |
| |
| <!-- ===================================================================================== --> |
| <p>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. |
| </p> |
| |
| |
| <!-- End Content Area --> |
| |
| <br> |
| <div class="feedback-box"><a href="https://netbeans.org/about/contact_form.html?to=3&subject=Feedback:%20Debugging%20Multithreaded%20Applications">Send Feedback on This Tutorial</a></div> |
| <br style="clear:both;" /> |
| <!-- ======================================================================================= --> |
| <h2><a name="nextsteps"></a>See Also</h2> |
| <p>For more information about developing and testing Java applications in NetBeans IDE, see the following resources:</p> |
| <ul> |
| <li>Demo: <a href="debug-multithreaded-screencast.html">Debugging a Multi-threaded Application in NetBeans IDE</a></li> |
| <li>Demo: <a href="debug-stepinto-screencast.html">Visual Step Into Action in NetBeans Debugger</a></li> |
| <li>Demo: <a href="debug-deadlock-screencast.html">Deadlock Detection Using the NetBeans Debugger</a></li> |
| <li>Demo: <a href="debug-evaluator-screencast.html">Using the Code Snippet Evaluator in the NetBeans Debugger</a></li> |
| <li><a href="../../trails/java-se.html">Basic IDE and Java Programming Learning Trail</a></li> |
| <li><a href="junit-intro.html">Writing JUnit Tests</a></li> |
| <li><a href="profiler-intro.html">Introduction to Profiling Java Applications</a></li> |
| </ul> |
| </body> |
| </html> |