core/org.eclipse.ptp.doc.user/html/06parDebugging.html - ptp/org.eclipse.ptp - Git at Google

 <html>
 <head>
 <title>Parallel Debugging</title>
 <link rel="stylesheet" type="text/css" href="help.css">
 <script type="text/javascript" src="thumb.js"> </script>
 </head>
 <body>
 <!-- test -->
 <h1>Parallel Debugging</h1>
 <p>This section describes the features of PTP that enable a developer to debug a parallel application. The topics that will be covered, include:</p>
 <ul>
 <li><a href="#feat">The Parallel Debug Perspective </a></li>
 <li><a href="#pSets">Process Sets</a></li>
 <li><a href="#pSetsOper">Operations on Process Sets</a></li>
 <li><a href="#pSetsCreate">Managing Process Sets</a></li>
 <li><a href="#bkpt">Breakpoints</a></li>
 <li><a href="#cip">Current Instruction Pointer</a></li>
 <li><a href="#reg">Process Registration </a> and the Debug view (including stack traces)</li>
 <li><a href="#finish">Terminating Execution</a></li>

 </ul>

 <h2 id="feat">The Parallel Debug perspective</h2>
 <p>The <b>Parallel Debug perspective</b> is used when debugging a parallel application. The default behavior is to switch to the
 perspective when a <a href="04pLaunchConfigDebug.html">debug session is launched</a>. Experienced Eclipse users will notice that many
 of the views are similar to those available in the CDT <b>Debug perspective</b>. Please refer to the <b>C/C++ Development User Guide</b> for
 a description of these views.</p>

 <p><img src="images/06ptpDebugPersp.png"></p>
 <p>This image shows a typical debug session. In the upper left of the perspective is the <b>Parallel Debug view</b> which shows the processes associated with the job, and allows bulk control of the processes. Underneath this is the <b>Debug view</b> which is the standard view showing process threads and stack frames. The source window shows a current line marker, which represents the current location of all 64 processes. In the upper right, the <b>Variables view</b> is showing the variables from the processes currently selected in the <b>Debug view</b>. There are also a number of other views available for setting breakpoints, manipulating signals, etc. Below this is the standard <b>Outline view</b>. At the very bottom are the standard <b>Problems</b>, <b>Console</b>, and <b>Memory</b> views.</p>

 <h2 id="pSets">Process Sets</h2>
 <p>A key concept for debugging parallel programs with PTP is the notion of a <i>process set</i>. Traditional debuggers apply operations to a single
 process.  Parallel debugging operations apply to arbitrary collections of processes (including a single process). The PTP debugger calls these arbitrary collections process sets, and uses them as a means of simultaneously referring to one or more processes.</p>

 <p>When a parallel debug session is first started, all processes are contained
 in a set, called the <b>Root</b> set.  Sets are always associated with a single Job.
 A job can have any number of process sets, and a set can contain from 1 to the
 number of processes in a job. Process sets from the same job can contain overlapping sets of processes. This is
 shown in the following diagram.</p>

 <p><img src="images/06pSets.png"></p>

 <p>Debug commands on the <b>Parallel Debug view</b> toolbar always apply to the <i>current process set</i>, which is the set of processes that is visible in the view.</p>

 <p><img src="images/06parallelDebugViewCmds.png"></p>

 <h2 id="pSetsOper">Operations on Process sets</h2>

 <p>PTP provides buttons on the toolbar of the <b>Parallel Debug view</b>
 to create, modify, and delete process sets, and to change
 the current process set.</p>

 <p><img src="images/06parallelDebugViewSets.png"></p>


 <h2 id="pSetsCreate">Managing 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>

 <p>For example, to select a rectangular set of processes:</p>

 <p><img src="images/06pSetSelect.png")</script></p>

 <p>Once the processes have been selected, create a process set clicking on the <b>Create Set button</b> <img src="images/06createProcessSetIcon.png">.</p>

 <p><img src="images/06selectProcessSetCreate.png")</script></p>

 <p>To add processes to an existing process set, select the processes you wish to add and click on
 the down-arrow <img src="images/06downArrowSelect.png"> to the right of the icon:</p>

 <p><img src="images/06selectProcessSetCreateAdd.png"></p>


 <p>To change the current process set, select the <b>Change Set button</b>
 <img src="images/06pSetChooseIcon.png">
 and choose from the list via the down-arrow <img src="images/06downArrowSelect.png">, or
 click on the button itself to cycle through the sets.</p>

 <p><img src="images/06pSetChange.png")</script></p>

 <p>To remove processes from the <i>current set</i>, select the processes
 as described above, and click the
 <b>Remove Elements button</b>.</p>

 <p><img src="images/06pSetRemove.png"></p>

 <p>Select the <b>Delete Set button</b> to delete the current process set:</p>

 <p><img src="images/06pSetDelete.png"></p>

 <h2 id="bkpt">Breakpoints</h2>
 <p>PTP has a special type of breakpoint known as a <i>parallel breakpoint</i>. These breakpoints differ from normal breakpoints because they apply to a set of processes instead of a single process (or thread). There are two types of parallel breakpoints:</p>

 <ul>
 <li><p><i>Global breakpoints</i> apply to <i>all</i> processes in <i>any</i> job. A global breakpoint remains in effect between job launches. Typically, a global breakpoint is used for gaining control of an application at a predetermined point. Global breakpoints are identified by a parallel breakpoint icon with a small <code>G</code> in the upper left corner:</p>

 <p><img src="images/06globalBreakpoint.png"></p>
 </li>

 <li><p><i>Set Breakpoints </i> apply only to a <i>specific set</i> of processes
 (which can include the root set) for a <i>single</i> job. When the job completes,
 these breakpoints are removed.</p>

 <p><img src="images/06setBreakpoint.png"></p>
 </li>
 <p>Set breakpoints can be one of three colors:<p>
 <ul>
 <li><p>Green indicates the breakpoint applies to the current set.</p></li>
 <li><p>Blue indicates the breakpoint applies to some other set than the current set, but there are overlapping processes in the sets.</p></li>
 <li><p>Yellow indicates the breakpoint applies to some other set than the current set, and there are no overlapping processes in the sets.</p></li>
 </ul>
 </ul>

 <h3>Setting a breakpoint</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.
 You can also right-click and use the <b>Parallel Breakpoint &gt; Toggle breakpoint</b> context menu.</p>

 <p><img src="images/06bkptSetContext.png"></p>

 <p>A global breakpoint is created if no jobs are selected in the <b>Parallel Debug view</b>.
 If a job is selected, the breakpoint will apply to the current set.</p>

 <h3>Breakpoint information</h3>

 <p>There are a number of ways to find out more information about a breakpoint, such as the source file, line and process set it applies to. Placing the mouse over a breakpoint will display a tooltip popup:</p>

 <p><img src="images/06bkptHover.png"></p>

 <p>The <b>Breakpoints view</b> can be used to see all breakpoints that have been created: </p>

 <p><img src="images/06bkptsView.png"></p>

 <p>Use <b>Show &gt; Parallel Breakpoint Set</b> in the menu on the <b>Breakpoints view</b> toolbar to group breakpoints
 by the process set they apply to:</p>

 <p><img src="images/06bkptsViewMenu.png"></p>

 <p>For example the above selection will list the breakpoints
 by process set:</p>

 <p><img src="images/06bkptsViewByProcessSet.png"></p>

 <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 only a single instruction pointer displayed at any one time.
 In parallel programs, there is an instruction pointer for every process.</p>

 <p>The PTP debugger shows one instruction pointer for
 <i>every group of processes at the same location</i>. In the following example, there are processes suspended
 at three different locations in the program.</p>

 <p><img src="images/06mip.png"></p>

 <p><i>The group of processes represented by an instruction pointer
 is not necessarily the same as a process set.</i></p>

 <p>Different markers are used to indicate the types of processes stopped at that location (the different types will be discussed below):</p>
 <ul>
 <li><p><img src="images/06ipReg.png">Registered processes marker</p></li>
 <li><p><img src="images/06ipUnreg.png">Un-registered processes marker</p></li>
 <li><p><img src="images/06ipMult.png">Marker indicating a combination of registered and un-registered processes</p></li>
 </ul>

 <p>Placing the mouse over an instruction pointer provides additional information about the processes suspended at that location:</p>
 <p><img src="images/06cipHover.png"></p>

 <h2 id="reg">Process Registration and the Debug View</h2>

 <p>Once processes of a parallel job have been suspended, it is often desirable to obtain more detailed information about an individual process. In order to do this, a particular process must first be <i>registered</i>. Once a process is registered it's threads and stack frames appear in the <b>Debug view</b>. By selecting the stack frame in this view, detailed information about the local variables can be obtained in the <b>Variables view</b>.</p>

 <p>Any number of processes can be registered, and processes can be registered or un-registered at any time. To register a process, double-click its process icon in the <b>Parallel Debug view</b>. A black box will be shown around the process icon to indicate that it has been registered. At the sime time, the process will appear in the <b>Debug view</b>.</p>

 <p><img src="images/06reg1.png"></p>

 <p>To un-register a process, double-click on the same process icon. The box disappears, and the process is removed from the debug view.</p>

 <p>The <b>Debug view</b> also provides a set of debug commands (resume, pause, step over, etc.) that apply to the <i>currently selected process</i> in the view. This provides a convenient means of controlling individual processes.</p>

 <h2 id="finish">Terminating Execution</h2>
 <p>At the end of a debug session, it is necessary to terminate the execution of the job. To do this, click on the terminate icon <img src="images/06terminateAll.png"> in the <b>Parallel Debug view</b>.  Note that the terminate icon in the <b>Debug view</b> <img src="images/06terminate.png"> will only terminate the currently selected process in that view.</p>

 <p><a href="#top">Back to Top</a> | <a href="toc.html">Back to Table of Contents</a>

 </body>
 </html>
	<html>
	<head>
	<title>Parallel Debugging</title>
	<link rel="stylesheet" type="text/css" href="help.css">
	<script type="text/javascript" src="thumb.js"> </script>
	</head>
	<body>
	<!-- test -->
	<h1>Parallel Debugging</h1>
	<p>This section describes the features of PTP that enable a developer to debug a parallel application. The topics that will be covered, include:</p>
	<ul>
	<li><a href="#feat">The Parallel Debug Perspective </a></li>
	<li><a href="#pSets">Process Sets</a></li>
	<li><a href="#pSetsOper">Operations on Process Sets</a></li>
	<li><a href="#pSetsCreate">Managing Process Sets</a></li>
	<li><a href="#bkpt">Breakpoints</a></li>
	<li><a href="#cip">Current Instruction Pointer</a></li>
	<li><a href="#reg">Process Registration </a> and the Debug view (including stack traces)</li>
	<li><a href="#finish">Terminating Execution</a></li>

	</ul>

	<h2 id="feat">The Parallel Debug perspective</h2>
	<p>The <b>Parallel Debug perspective</b> is used when debugging a parallel application. The default behavior is to switch to the
	perspective when a <a href="04pLaunchConfigDebug.html">debug session is launched</a>. Experienced Eclipse users will notice that many
	of the views are similar to those available in the CDT <b>Debug perspective</b>. Please refer to the <b>C/C++ Development User Guide</b> for
	a description of these views.</p>

	<p><img src="images/06ptpDebugPersp.png"></p>
	<p>This image shows a typical debug session. In the upper left of the perspective is the <b>Parallel Debug view</b> which shows the processes associated with the job, and allows bulk control of the processes. Underneath this is the <b>Debug view</b> which is the standard view showing process threads and stack frames. The source window shows a current line marker, which represents the current location of all 64 processes. In the upper right, the <b>Variables view</b> is showing the variables from the processes currently selected in the <b>Debug view</b>. There are also a number of other views available for setting breakpoints, manipulating signals, etc. Below this is the standard <b>Outline view</b>. At the very bottom are the standard <b>Problems</b>, <b>Console</b>, and <b>Memory</b> views.</p>

	<h2 id="pSets">Process Sets</h2>
	<p>A key concept for debugging parallel programs with PTP is the notion of a <i>process set</i>. Traditional debuggers apply operations to a single
	process. Parallel debugging operations apply to arbitrary collections of processes (including a single process). The PTP debugger calls these arbitrary collections process sets, and uses them as a means of simultaneously referring to one or more processes.</p>

	<p>When a parallel debug session is first started, all processes are contained
	in a set, called the <b>Root</b> set. Sets are always associated with a single Job.
	A job can have any number of process sets, and a set can contain from 1 to the
	number of processes in a job. Process sets from the same job can contain overlapping sets of processes. This is
	shown in the following diagram.</p>

	<p><img src="images/06pSets.png"></p>

	<p>Debug commands on the <b>Parallel Debug view</b> toolbar always apply to the <i>current process set</i>, which is the set of processes that is visible in the view.</p>

	<p><img src="images/06parallelDebugViewCmds.png"></p>

	<h2 id="pSetsOper">Operations on Process sets</h2>

	<p>PTP provides buttons on the toolbar of the <b>Parallel Debug view</b>
	to create, modify, and delete process sets, and to change
	the current process set.</p>

	<p><img src="images/06parallelDebugViewSets.png"></p>


	<h2 id="pSetsCreate">Managing 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>

	<p>For example, to select a rectangular set of processes:</p>

	<p><img src="images/06pSetSelect.png")</script></p>

	<p>Once the processes have been selected, create a process set clicking on the <b>Create Set button</b> <img src="images/06createProcessSetIcon.png">.</p>

	<p><img src="images/06selectProcessSetCreate.png")</script></p>

	<p>To add processes to an existing process set, select the processes you wish to add and click on
	the down-arrow <img src="images/06downArrowSelect.png"> to the right of the icon:</p>

	<p><img src="images/06selectProcessSetCreateAdd.png"></p>


	<p>To change the current process set, select the <b>Change Set button</b>
	<img src="images/06pSetChooseIcon.png">
	and choose from the list via the down-arrow <img src="images/06downArrowSelect.png">, or
	click on the button itself to cycle through the sets.</p>

	<p><img src="images/06pSetChange.png")</script></p>

	<p>To remove processes from the <i>current set</i>, select the processes
	as described above, and click the
	<b>Remove Elements button</b>.</p>

	<p><img src="images/06pSetRemove.png"></p>

	<p>Select the <b>Delete Set button</b> to delete the current process set:</p>

	<p><img src="images/06pSetDelete.png"></p>

	<h2 id="bkpt">Breakpoints</h2>
	<p>PTP has a special type of breakpoint known as a <i>parallel breakpoint</i>. These breakpoints differ from normal breakpoints because they apply to a set of processes instead of a single process (or thread). There are two types of parallel breakpoints:</p>

	<ul>
	<li><p><i>Global breakpoints</i> apply to <i>all</i> processes in <i>any</i> job. A global breakpoint remains in effect between job launches. Typically, a global breakpoint is used for gaining control of an application at a predetermined point. Global breakpoints are identified by a parallel breakpoint icon with a small <code>G</code> in the upper left corner:</p>

	<p><img src="images/06globalBreakpoint.png"></p>
	</li>

	<li><p><i>Set Breakpoints </i> apply only to a <i>specific set</i> of processes
	(which can include the root set) for a <i>single</i> job. When the job completes,
	these breakpoints are removed.</p>

	<p><img src="images/06setBreakpoint.png"></p>
	</li>
	<p>Set breakpoints can be one of three colors:<p>
	<ul>
	<li><p>Green indicates the breakpoint applies to the current set.</p></li>
	<li><p>Blue indicates the breakpoint applies to some other set than the current set, but there are overlapping processes in the sets.</p></li>
	<li><p>Yellow indicates the breakpoint applies to some other set than the current set, and there are no overlapping processes in the sets.</p></li>
	</ul>
	</ul>

	<h3>Setting a breakpoint</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.
	You can also right-click and use the <b>Parallel Breakpoint > Toggle breakpoint</b> context menu.</p>

	<p><img src="images/06bkptSetContext.png"></p>

	<p>A global breakpoint is created if no jobs are selected in the <b>Parallel Debug view</b>.
	If a job is selected, the breakpoint will apply to the current set.</p>

	<h3>Breakpoint information</h3>

	<p>There are a number of ways to find out more information about a breakpoint, such as the source file, line and process set it applies to. Placing the mouse over a breakpoint will display a tooltip popup:</p>

	<p><img src="images/06bkptHover.png"></p>

	<p>The <b>Breakpoints view</b> can be used to see all breakpoints that have been created: </p>

	<p><img src="images/06bkptsView.png"></p>

	<p>Use <b>Show > Parallel Breakpoint Set</b> in the menu on the <b>Breakpoints view</b> toolbar to group breakpoints
	by the process set they apply to:</p>

	<p><img src="images/06bkptsViewMenu.png"></p>

	<p>For example the above selection will list the breakpoints
	by process set:</p>

	<p><img src="images/06bkptsViewByProcessSet.png"></p>

	<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 only a single instruction pointer displayed at any one time.
	In parallel programs, there is an instruction pointer for every process.</p>

	<p>The PTP debugger shows one instruction pointer for
	<i>every group of processes at the same location</i>. In the following example, there are processes suspended
	at three different locations in the program.</p>

	<p><img src="images/06mip.png"></p>

	<p><i>The group of processes represented by an instruction pointer
	is not necessarily the same as a process set.</i></p>

	<p>Different markers are used to indicate the types of processes stopped at that location (the different types will be discussed below):</p>
	<ul>
	<li><p><img src="images/06ipReg.png">Registered processes marker</p></li>
	<li><p><img src="images/06ipUnreg.png">Un-registered processes marker</p></li>
	<li><p><img src="images/06ipMult.png">Marker indicating a combination of registered and un-registered processes</p></li>
	</ul>

	<p>Placing the mouse over an instruction pointer provides additional information about the processes suspended at that location:</p>
	<p><img src="images/06cipHover.png"></p>

	<h2 id="reg">Process Registration and the Debug View</h2>

	<p>Once processes of a parallel job have been suspended, it is often desirable to obtain more detailed information about an individual process. In order to do this, a particular process must first be <i>registered</i>. Once a process is registered it's threads and stack frames appear in the <b>Debug view</b>. By selecting the stack frame in this view, detailed information about the local variables can be obtained in the <b>Variables view</b>.</p>

	<p>Any number of processes can be registered, and processes can be registered or un-registered at any time. To register a process, double-click its process icon in the <b>Parallel Debug view</b>. A black box will be shown around the process icon to indicate that it has been registered. At the sime time, the process will appear in the <b>Debug view</b>.</p>

	<p><img src="images/06reg1.png"></p>

	<p>To un-register a process, double-click on the same process icon. The box disappears, and the process is removed from the debug view.</p>

	<p>The <b>Debug view</b> also provides a set of debug commands (resume, pause, step over, etc.) that apply to the <i>currently selected process</i> in the view. This provides a convenient means of controlling individual processes.</p>

	<h2 id="finish">Terminating Execution</h2>
	<p>At the end of a debug session, it is necessary to terminate the execution of the job. To do this, click on the terminate icon <img src="images/06terminateAll.png"> in the <b>Parallel Debug view</b>. Note that the terminate icon in the <b>Debug view</b> <img src="images/06terminate.png"> will only terminate the currently selected process in that view.</p>

	<p><a href="#top">Back to Top</a> \| <a href="toc.html">Back to Table of Contents</a>

	</body>
	</html>