| <html> |
| <head> |
| <title>The PTP Debug Perspective</title> |
| </head> |
| <body> |
| <!-- test --> |
| <h1>The PTP Debug Perspective</h1> |
| <ul> |
| <li><a href="#feat">PTP Debug Perspective </a> - main features |
| <li><a href="#pSets">Process Sets</a> |
| <li><a href="#pSetsOper">Operations on Process Sets</a> |
| <li><a href="#pSetsCreate">Creating Process Sets</a> |
| <li><a href="#bkpt">Breakpoints</a> |
| <li><a href="#cip">Current Instruction Pointer</a> |
| <li><a href="#reg">Process Registration </a> and the Debug view (including stack traces) |
| <li><a href="#ptpVar">PTP Variable View</a> |
| |
| </ul> |
| |
| <h2 id="feat">Main features of the PTP Debug perspective</h2> |
| <p>Here is a view of the PTP Debug perspective, showing |
| <ul> |
| <li>the Jobs view of currently running jobs, including |
| the processes in the current process set, |
| <li>the debug process view which shows the call stack |
| for any registered processes |
| <li>the source view (from CDT) which shows |
| the current instruction pointer of the process selected |
| in the debug process view |
| <li>the variables view that shows |
| the current values of variables for the currently selected |
| process in the debug process view |
| <li>the outline view (from CDT) |
| </ul> |
| <img src="images/ptpDebugOview.gif"> |
| |
| |
| <h2>Launching a parallel debug session</h2> |
| <ul> |
| <li>Create a Parallel Application for Debug launch |
| similar to creating it for Run... |
| (See <a href="02pLaunchConfig.html">Launching parallel programs</a>, |
| but the necessary information is given below.) |
| </li> |
| <p>In the Debug launch dialog (Run -> Debug ... or use the Debug |
| icon on the eclipse toolbar) |
| <li>Select 'Debugger' tab.. |
| <li>Select 'Stop in main' to automatically stop the job</li> |
| <li>Make sure the Debugger is set to "SDM" - use the pulldown menu. |
| <li>Change any other default settings (not normally required)</li> |
| <li>Select the Debug button (or hit "Apply" to save these settings |
| if you do not intend to launch immediately.) |
| <br><img src="images/parDebugConfig.gif"> |
| <p>For existing Parallel Application launch configurations, |
| you can simply |
| launch using the debug button rather than the Run button |
| <p> |
| <img src="images/parDebugIcon.gif"> |
| </li> |
| |
| <li>Eclipse may ask you to switch to the PTP Debug perspective. |
| <br><img src="images/confirmPerspSwitch.gif"> |
| <br>Answer yes; if you check "Remember my decision" it won't ask you this |
| for future launches. It will then |
| switch to the PTP Debug perspective.</li> |
| </ul> |
| <p>The Parallel Debug Perspective: |
| <p><img src="images/ptpDebugPersp.gif"> |
| <br>The debug perspective appears as in the example above. |
| This is a launch with 32 processes set on the launch configuration. |
| The Parallel Debug view shows the 32 processes (yellow diamonds |
| indicate a stopped process); the Debug view shows process 0 |
| stopped at main; the Source view shows the line at which process |
| 0 is stopped. |
| <p>Note that the breakpoints view (upper right) is empty, since |
| no breakpoints are set. You can view the variables in this area |
| by selecting the tab on the Variables View |
| <br><img src="images/variablesViewSelect.gif"> |
| <br>Note that most variables don't have valid values |
| yet since we haven't executed their initializations in the |
| program. |
| <br><img src="images/variablesViewDisplay.gif"> |
| |
| <h2 id="pSets">Process Sets</h2> |
| <p>Traditional debuggers apply operations to a single |
| process. Parallel debugging operations apply to a single process |
| <i>or to arbitrary collections of processes.</i> |
| <p>A <i>process set </i> is a means of simultaneously referring |
| to one or more processes. |
| |
| <p>When a parallel debug session is first started, all processes are placed |
| in a set, called the 'Root' set. Sets are always associated with a single Job. |
| A job can have any number of process sets. A set can contain from 1 to the |
| number of processes in a job. |
| <p><img src="images/pSets.gif"> |
| <h2 id="pSetsOper">Operations on Process sets</h2> |
| <p>Use the icons in the toolbar of the Parallel Debug view |
| to create, modify, and delete process sets, and to change |
| the current process set. |
| <br><img src="images/pSetOper.gif"> |
| <p>Debug operations on the Parallel Debug View toolbar always apply to the current set. |
| <br><img src="images/pSetDebug.gif"> |
| |
| <h2 id="pSetsCreate">Creating Process Sets</h2> |
| |
| <p>Select the processes to be placed in the set |
| by selecting a rectangular region with the mouse, |
| or click the mouse and shift-click or ctrl-click to |
| select a contiguous region, or separate processes, respectively. |
| |
| <p>Selecting a rectangular set: |
| <br><img src="images/pSetSelect.gif"> |
| <p>Create a process set from the group that was selected by |
| clicking on the <i>image</i> in the icon <img src="images/createProcessSetIcon.gif">.. |
| <p><img src="images/selectProcessSetCreate.gif"> |
| |
| <p>Or, add the group of processes to an existing process set by clicking |
| on the <img src="images/downArrowSelect.gif"> down-arrow to the right of the icon: |
| <p><img src="images/selectProcessSetCreateAdd.gif"> |
| |
| |
| <p>To change the current process set, select the icon |
| <img src="images/pSetChooseIcon.gif"> |
| and choose from the list via the down-arrow <img src="images/downArrowSelect.gif">, or |
| click on the image in the icon itself to cycle through the sets. |
| <br><img src="images/pSetChange.gif"> |
| |
| <p>To remove processes from <i>the current set</i>, select the processes |
| as described above, and Click the |
| "Remove Elements" button. |
| <br><img src="images/pSetRemove.gif"> |
| <p>Select the "Delete Set" icon to delete the current process set. |
| <br><img src="images/pSetDelete.gif"> |
| <br><img src="images/pSetDeleteConfirm.gif"> |
| |
| <h2 id="bkpt">Breakpoints</h2> |
| <p>There are two main types of parallel breakpoints in PTP. |
| <ul> |
| <li><i>Global Breakpoints</i> apply to <i>all</i> processes in <i>any</i> job. |
| They are saved between jobs. |
| <br><img src="images/bkptGlobal.gif"> |
| <p> |
| </li> |
| <li><i>Set Breakpoints </i> apply only to a process in a particular set |
| (which can include the root set) for a single job. When the job completes, |
| the breakpoints are no longer available. |
| <p>Green indicates the breakpoint is applied to the current set. |
| <br>Blue indicates the breakpoint is applied to some other set. |
| <br>Yellow indicates the breakpoint is applied to some process(es) |
| in the current set, which are also in some other set. |
| (In other words, the process sets overlap.) |
| <br><img src="images/bkptSet.gif"> |
| |
| </li> |
| |
| </ul> |
| |
| <h3>Setting Breakpoints</h3><p> |
| To create a breakpoint, double-click on the left edge of |
| an editor window, at the line on which you want to set the breakpoint. |
| Or, right click and use the context menu. |
| <br><img src="images/bkptSetContext.gif"> |
| <p>A global breakpoint is created if no jobs are selected. |
| If a job is selected, the breakpoint will apply to the current set. |
| <h3>Breakpoint information</h3> |
| <p>Hover over a breakpoint to see more information. |
| <br><img src="images/bkptHover.gif"> |
| <p>Use the Breakpoints view to see all breakpoints. |
| <br><img src="images/bkptsView.gif"> |
| <p>Use the menu in the Breakpoints view to group breakpoints |
| by type. |
| <br><img src="images/bkptsViewMenu.gif"> |
| <p>For example the above selection will list the breakpoints |
| by process set. |
| <br><img src="images/bkptsViewByProcessSet.gif"> |
| |
| <h2 id="cip">Current Instruction Pointer</h2> |
| <p>The current instruction pointer is used to show the current |
| location of <i>suspended</i> processes. |
| In traditional programs, there is a single instruction pointer. |
| (The exception to this is multi-threaded programs.) |
| In parallel programs, there is an instruction pointer for every process. |
| <p>The PTP debugger shows one instruction pointer for |
| <i>every group of processes at the same location</i>. |
| <blockquote><b>Note:</b> The group of processes represented by an instruction pointer |
| is not necessarily the same as a process set.</blockquote> |
| <p>In the normal debugger, the single instruction pointer |
| is indicated with the blue arrow icon. The current source line is also highlighted. |
| <br><img src="images/sip.gif"> |
| <p>In the PTP (parallel) debugger, there are multiple instruction pointers. |
| The marker depends on the type of process stopped at that location. |
| <ul> |
| <li><img src="images/ipMult.gif">Multiple processes marker |
| <li><img src="images/ipReg.gif">Registered process marker |
| <li><img src="images/ipUnreg.gif">Un-registered process marker |
| </ul> |
| <p>The highlight color of the current instruction pointer |
| depends on the stack frame. In the following image, |
| the green background indicates a registered process; the brown background indicates an |
| unregistered process. The blue band behind the highlight color of the line tracks |
| the current stack frame. |
| <p><img src="images/ptpInstrPtr.gif"> |
| |
| |
| <p>Hovering over the instruction pointer provides additional information. |
| <br><img src="images/cipHover.gif"> |
| <h2 id="reg">Process Registration and the Debug View</h2> |
| |
| <p>Process set commands apply to groups of processes. |
| For finer control and more detailed information, a process can be |
| <i>registered</i> and isolated in the Debug View. |
| <p> |
| Registered processes, including their stack traces, appear in the 'Debug' view. |
| Any number of processes can be registered, |
| and processes can be registered or un-registered at any time. |
| <p>To register a process, double-click its process icon in the Jobs view. |
| Note that the process "diamond" then is surrounded by a box. |
| The process appears in the debug view. |
| <br><img src="images/reg1.gif"> |
| <p>To un-register a process, double-click on the same icon. |
| The box disappears, and the process is removed from the debug view. |
| <p>Note that the debug commands (icons including run, step, etc.) |
| in the toolbar of the Jobs view (tab title: Parallel Debug) |
| control the currently selected process set. |
| The debug commands in the toolbar of the Debug view |
| control the single process that is currently selected in that view. |
| <h2 id="ptpVar">PTP Variable View</h2> |
| <p>The PTP Variable view allows you to |
| view a particular variable's values across the various processes. |
| |
| <p>If you open the PTP Variable View (Window -> Show View -> Other) |
| you can add a variable. |
| <br> |
| <img src="images/ptpVarAdd1.png"> |
| <p>This opens the PTP Variable Dialog which allows you to select a variable or expression, |
| and a process set (use Root for all processes) for which to create the variable to watch for each process. |
| <br> |
| <img src="images/ptpVarAdd.png"> |
| <p> |
| Then when you mouse over a process icon in the |
| Parallel Debug view, it will show the value of the variable in the tooltip. |
| <br> |
| <img src="images/ptpVarDisplay.png"> |
| <h2>Putting it all together</h2> |
| <p>Note that with the above instructions, you should now be able to do the following: |
| <i>Answers are in italics.</i> |
| <ul> |
| <li>Set a global breakpont |
| <br><i>Make sure no job is selected, then double-click in the area to the left of the source line. You should see |
| the global breakpoint icon <img src="images/globalBkpt.gif"> appear. </i> |
| </li> |
| <li>Start a 100 process job |
| <br><i>Use the menu: Debug->Debug... Make a launch configuration (or reuse one). |
| On the Parallel tab, specify 100 processes.</i> |
| </li> |
| <li>When the breakpoint is reached,</li> |
| <ul> |
| <li>Create a process set containing processes 0-10 (set_1) |
| <br><i>In the Parallel Debug view, select a group of the process diamonds, |
| which should be yellow=stopped processes. |
| Select a rectangular region with the mouse, or click the mouse and shift-click |
| or ctrl-click to select a contiguous region, or separate processes, respectively. |
| Then click the <img src="images/createProcessSet.gif"> button and give |
| the process the name "set_1" |
| </i> |
| <li>Create a process set containing processes 20-30 (set_2) |
| <br><i>Same as above.</i> |
| <li>Single step all processes |
| <br><i>Use the step-over icon <img src="images/fromPTP/stepover_normal.gif"> in the toolbar of the |
| Parallel Debug View (near the top).</i> |
| <li>Single step processes in set_1 |
| <br><i>Make sure the process set is selected via |
| <img src="images/selectProcessSet.gif">, then use the step-over icon <img src="images/fromPTP/stepover_normal.gif"> in the toolbar of the |
| Parallel Debug View (near the top).</i> |
| <li>Register a process |
| <br><i>Double-click on the process icon diamond. It should then have a rectangle around it. </i> |
| <li>Single step the registered process |
| <br><i>Select the process in the debug view (near the center of the screen), and Use the step-over icon <img src="images/fromPTP/stepover_normal.gif"> in the toolbar of the |
| Debug View (near the top).</i> |
| <li>Select a stack frame and view the variables |
| <br><i>Click on a line in the Debug view that includes a line number.</i> |
| </ul> |
| <li>Terminate execution |
| <br><i>Click on the terminate icon <img src="images/terminateAll.gif"> in the |
| Parallel Debug View. Note that the terminate icon in the Debug (Process) |
| view <img src="images/terminate.gif">will terminate a single process.</i> |
| </li> |
| |
| </ul> |
| |
| |
| |
| |
| <p><a href="#top">Back to Top</a> | <a href="toc.html">Back to Table of Contents</a> |
| |
| </body> |
| </html> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |