IBM Books

Operation and Use, Volume 2

Manipulating the function call tree

Xprofiler lets you look at your profiled data a number of ways, depending on what you want to see. It provides:

Zooming in on the function call tree

Xprofiler lets you magnify specific areas of the window to get a better view of your profiled data. The View menu includes three options that let you do this:

To resize a specific area of the display, you can use either the Overview or Zoom In options of the View menu. To magnify an area with the Overview option:

  1. Select the View menu, and then the Overview option. The Overview Window appears, as in the example below.

Figure 10. The Overview Window

View figure.

The Overview Window contains a miniature view of the function call tree, just as it appears in the Xprofiler main display. When you open the Overview Window, the light blue highlight area represents the current view of the main window.

You control the size and placement of the highlight area with your mouse. Depending on where you place your mouse over the highlight area, your cursor changes to indicate the operation you can perform. Here is an explanation of the cursor images, and what they indicate to you:

When your cursor appears as two crossed arrows, it means that by pressing and holding your mouse button, you can control where the box is placed.

Figure 11. Cursor when movement of highlight box is under mouse control

View figure.

When your cursor appears as a line with an arrow perpendicular to it, it means that your mouse button has grabbed the edge of the highlight area, and you now have the ability to resize it. By pressing and holding your mouse button, and dragging it in or out, you can increase or decrease the size of the box. Notice that as you move the edge in or out, the size of the entire highlight area changes.

Figure 12. Cursor when edge of highlight box is under mouse control

View figure.

When your cursor appears as a right angle with an arrow pointing into it, it means that your mouse button has grabbed the corner of the highlight area and you now have the ability to resize it. By pressing and holding your mouse button, and dragging it diagonally up or down, you can increase or decrease the size of the box. Notice that as you move the corner up or down, the size of the entire highlight area changes.

Figure 13. Cursor when corner of highlight box is under mouse control

View figure.

3. Place your mouse cursor within the light blue highlight area. Notice that the cursor changes to four crossed arrows. This indicates that your cursor has control over the placement of the box.
4. Move your cursor over one of the four corners of the highlight area. Notice that the cursor changes to a right angle with an arrow pointing into it. This indicates that you now have control over the corner of the highlight area.
5. Press and hold the left mouse button, and drag the corner of the box diagonally inward. The box shrinks as you move it. The example below shows the highlight area reduced in size, with only a few function boxes visible within it.

Figure 14. Highlight Area Reduced in Size

View figure.

6. When the highlight area is as small as you would like it (or the smallest allowable size), release the mouse button. The Xprofiler main display redraws itself to contain only the functions within the highlight area, and in the same proportions. This has the effect of magnifying the items within the highlight area.
7. Place your mouse cursor over the highlight area. Your cursor again changes to four crossed arrows to indicate that you have control over the placement of the highlight area. Press and hold the left mouse button and drag the highlight area to the area of the Xprofiler display you want to magnify.
8. Release the mouse button. The Xprofiler main display now contains the items in which you are interested.

The example below shows the Xprofiler main display with the area, indicated by the highlight area in Figure 14, magnified. Note that the performance data, on the label of each function box, is now visible.

Figure 15. Magnified View of Xprofiler Display

View figure.

To use the Zoom In option of the View menu to magnify a specific area of the function call tree:

  1. Select the View menu, and then the Zoom In option. Once you select the Zoom In option, your cursor changes to a hand to indicate that your selection is active.
  2. Place the mouse cursor in the upper left hand corner of the area you would like to view more closely. Press and hold the left mouse button while dragging it diagonally downward, until the rubber band box surrounds the area you want to view.
  3. Release the mouse button. Xprofiler redraws the display so that the area of the function call tree you selected is centered and sized proportionately, according to the size of the rubber band box you drew.

To get an even closer view of the area you selected, choose the Zoom In option again and follow the steps above.

There may be times when you are looking at the function call tree too closely. The Zoom Out option lets you widen the view of the function call tree, as if you were taking a few steps back from a painting on a wall.

The Zoom Out option is most useful after using the Zoom In or Overview options to magnify an area of the function call tree. By default, the Xprofiler main window is completely zoomed out (it shows you the entire function call tree). The Zoom Out option helps you return the main window to this state.

To zoom out:

  1. Select the View menu, and then the Zoom Out option. Once you select the Zoom Out option, your cursor changes to a hand to indicate that your selection is active.
  2. Place the mouse cursor in the upper left hand corner of the area you want to view. Press and hold the left mouse button while dragging it diagonally downward, until the rubberband box surrounds the area you want to widen.
  3. Release the mouse button. Xprofiler redraws the display so that the area of the function call tree you selected is centered and sized proportionately according to the size of the rubber band box that you drew.

To further step back from the area you selected, choose the Zoom Out option again, and follow the steps above.

Controlling how the display is updated

The Utility menu of the Overview window lets you choose the mode in which the display is updated. The default is the Immediate Update option, which causes the display to show you the items in the highlight area as you are moving it around. The Delayed Update option, on the other hand, causes the display to be updated only when you have moved the highlight area over the area in which you are interested, and released the mouse button. The Immediate Update option only applies to what you see when you move the highlight area; it has no effect on the resizing of items in highlight area, which is always delayed.

Other viewing options

Xprofiler lets you change the way it displays the function call tree, based on your own personal preferences.

Controlling the graphic style of the function call tree

You can choose between 2-D and 3-D function boxes in the function call tree. The default style is 2-D, but you can change this to 3-D. To do this:

  1. Select the View menu, and then the 3-D Image option. The function boxes in the function call tree now appear in 3-D format.

Controlling the orientation of the function call tree

You can choose to have Xprofiler display the function call tree in either Top-to-Bottom or Left-to-Right format. The default is Top-to-Bottom. If you would rather see the function call tree displayed in Left-to-Right format:

  1. Select the View menu, and then the Layout: Left>Right option. The function call tree appears in Left-to-Right format.

Figure 16. Left-to-Right Format

View figure.

Controlling the representation of the function call tree

You can choose to have Xprofiler represent the function call tree in either summary mode or average mode.

When you select the Summary Mode option of the View menu, the size and shape of each function box is determined by the total CPU time of multiple gmon.out files used on that function alone, and the total time used by the function and its descendant functions. The height of each function node represents the total CPU time used on the function itself. The width of each node represents the total CPU time used on the function and its descendant functions. When the display is in summary mode, the Summary Mode option is greyed out and the Average Mode option is activated.

When you select the Average Mode option of the View menu, the size and shape of each function box is determined by the average CPU time used on that function alone, among all loaded gmon.out files, and the standard deviation of CPU time for that function among all loaded gmon.out files. The height of each function node represents the average CPU time, among all the input gmon.out files, used on the function itself. The width of each node represents the standard deviation of CPU time, among the gmon.out files, used on the function itself.

The purpose of average mode is to reveal workload balancing problems when an application is involved with multiple gmon.out files. In general, a function node with large standard deviation has a wide width, and a node with small standard deviation has a slim width.

Both summary mode and average mode only affect the appearance of the function call tree and the labels associated with it. All the performance data in Xprofiler reports and code displays are always summary data. If only one gmon.out file is given, both Summary Mode and Average Mode will be greyed out, and the display is always in Summary Mode.

Filtering what you see

When Xprofiler first opens, the entire function call tree appears in the main window. This includes the function boxes and call arcs that belong to your executable as well as the shared libraries that it utilizes. At times, you may want to simplify what you see in the main window, and there are a number of ways to do this.

Note:
Filtering options of the Filter menu let you change the appearance of the function call tree only. The performance data contained in the reports (via the Reports menu) is not affected.

Restoring the status of the function call tree

Xprofiler allows you to undo operations that involve adding or removing nodes and arcs from the function call tree. When you undo an operation, you reverse the effect of any operation which adds or removes function boxes or call arcs to the function call tree. When you select the Undo option, the function call tree is returned to its appearance just prior to the performance of the add or remove operation. To undo an operation:

  1. Select the Filter menu, and then the Undo option. The function call tree is returned to its appearance just prior to the performance of the add or remove operation.

Whenever you invoke the Undo option, the function call tree loses its zoom focus and zooms all the way out to reveal the entire function call tree in the main display. When you start Xprofiler, the Undo option is greyed out. It is activated only after an add or remove operation involving the function call tree takes place. After you undo an operation, the option greys out again until the next add or remove operation takes place.

The options that activate the Undo option include:

If a dialog, like the Load Configuration Dialog or the Filter by CPU Time Dialog, is invoked and then cancelled immediately, the status of the Undo option is not affected. Once the option is available, it stays that way until you invoke it, or a new set of files is loaded into Xprofiler through the Load Files Dialog.

Displaying the entire function call tree

When you first open Xprofiler, by default, all the function boxes and call arcs of your executable and its shared libraries appear in the main window. After that, you may choose to filter out specific items from the window. However, there may be times when you want to see the entire function call tree again, without having to reload your application. To do this:

  1. Select the Filter menu, and then the Show Entire Call Tree option. Xprofiler erases whatever is currently displayed in the main window and replaces it with the entire function call tree.

Excluding and including specific objects

There are a number of ways that Xprofiler lets you control the items that get displayed in the main window. For the most part, you will want to include or exclude certain objects so that you can more easily focus on the things that are of most interest to you.

Filtering shared library functions

In most cases, your application will call functions that are within shared libraries. By default, these shared libraries will appear in the Xprofiler window along with your executable. As a result, the window may get crowded and obscure the items that you really want to see. If this is the case, you may want to filter the shared libraries from the display. To do this:

  1. Select the Filter menu, and then the Remove All Library Calls option.

The shared library function boxes disappear from the function call tree, leaving only the function boxes of your executable file visible.

If you removed the library calls from the display, you may want to add all or some of them back. To do this:

  1. Select the File menu, and then the Add Library Calls option

The function boxes once again appear with the function call tree. Note, however, that all of the shared library calls that were in the initial function call tree may not be added back. This is because the Add Library Calls option only adds back in the function boxes for the library functions that were called by functions that are currently displayed in the Xprofiler window.

There may be times when you want to add only specific function boxes back into the display. To do this:

  1. Select the Filter menu, and then the Filter by Function Names option. The Filter By Function Names Dialog window appears.
  2. From the Filter By Function Names Dialog window, select the add these functions to graph button, and then type the name of the function you want to add in the Enter function name field. If you enter more than one function name, you must separate them by putting a blank space between each function name string.

    If there are multiple functions in your program that include the string you enter in their names, the filter applies to each one. For example, say you specified sub, and print, and your program also included functions named sub1, psub1 and printf. The sub, sub1, psub1, print, and printf functions would all be added to the graph.

  3. Click on the OK button. The function box(es) appears in the Xprofiler display with the function call tree.

Filtering by function characteristics

The Filter menu of Xprofiler offers you three options that allow you to add or subtract function boxes from the main window, based on specific characteristics. The options are:

Each one of these options uses a different dialog window to let you specify the criteria by which you want to include or exclude function boxes from the window.

To filter by function names:

1. Select the Filter menu.
2. Select the Filter by Function Names option. The Filter By Function Names Dialog window appears.

Figure 17. Filter By Function Names Dialog window

View figure.

3. The Filter By Function Names Dialog window includes three options:

From the Filter By Function Names Dialog window, select the option you want, and then type the name of the function(s) to which you want it applied in the Enter function name field. For example, say you wanted to remove function box for a function called printf, from the main window. You would click on the remove this function from the graph button and type printf in the Enter function name field.

You can enter more than one function name in this field. If there are multiple functions in your program that include the string you enter in their names, the filter will apply to each one. For example, say you specified sub and print, and your program also included functions named sub1, psub1, and printf. The option you chose would be applied to the sub, sub1, psub1, print, and printf functions.

4. Click on the OK button. The contents of the function call tree now reflect the filtering options you specified.

To filter by CPU time:

1. Select the Filter menu.
2. Select the Filter by CPU Time option. The Filter By CPU Time Dialog window appears.

Figure 18. Filter By CPU Time Dialog window

View figure.

3. The Filter By CPU Time Dialog window includes two options:
4. Click on the button for the option you want (show functions consuming the most CPU time is the default).
5. Select the number of functions to which you want it applied (1 is the default). You can move the slider in the Functions bar until the desired number appears, or you can enter the number in the Slider Value field. The slider and Slider Value field are synchronized so when the slider is updated, the text field value is updated also. If you enter a value in the text field, the slider is updated to that value when you click on the Apply button or the OK button.

For example, if you wanted to display the function boxes for the 10 functions in your application that consumed the most CPU, you would select the show functions consuming the most CPU button, and specify 10 with the slider or enter the value 10 in the text field.

6. Click on the Apply button to show the changes to the function call tree without closing the dialog. Click on the OK button to show the changes and close the dialog.

To filter by call counts:

1. Select the Filter menu.
2. Select the Filter by Call Counts option. The Filter By Call Counts Dialog window appears.

Figure 19. Filter By Call Counts Dialog window

View figure.

3. The Filter By Call Counts Dialog window includes two options:
4. Click on the button for the option you want (show arcs with the most call counts is the default).
5. Select the number of call arcs to which you want it applied (1 is the default). You can move the slider in the Call Arcs bar until the desired number appears, or you can enter the number in the Slider Value field. The slider and Slider Value field are synchronized so when the slider is updated, the text field value is updated also. If you enter a value in the text field, the slider is updated to that value when you click on the Apply button or the OK button.

For example, if you wanted to display the 10 call arcs in your application that represented the least number of calls, you would select the show arcs with the least call counts button, and specify 10 with the slider or enter the value 10 in the text field.

6. Click on the Apply button to show the changes to the function call tree without closing the dialog. Click on the OK button to show the changes and close the dialog.

Including and excluding parent and child functions

When tuning the performance of your application, you will want to know which functions consumed the most CPU time, and then you will need to ask several questions in order to understand their behavior:

Once you understand how these functions behave, and are able to improve their performance, you can move on to analyzing the functions that consume less CPU.

When your application is large, the function call tree will also be large. As a result, the functions that are the most CPU-intensive may be difficult to see in the function call tree. To get around this, use the Filter by CPU option of the Filter menu, which lets you display only the function boxes for the functions that consume the most CPU time. Once you've done this, the Function menu for each function lets you add the parent and descendant function boxes to the function call tree. By doing this, you create a smaller, simpler function call tree that displays the function boxes associated with most CPU-intensive area of the application.

A child function is one that is directly called by the function of interest. To see only the function boxes for the function of interest and its child functions:

  1. Place your mouse cursor over the function box in which you are interested, and press the right mouse button. The Function menu appears.
  2. From the Function menu, select the Immediate Children option, and then the Show Child Functions Only option.

    Xprofiler erases the current display and replaces it with only the function boxes for the function you chose, plus its child functions.

A parent function is one that directly calls the function of interest. To see only the function box for the function of interest and its parent functions:

  1. Place your mouse cursor over the function box in which you are interested, and press the right mouse button. The Function menu appears.
  2. From the Function menu, select the Immediate Parents option, and then the Show Parent Functions Only option.

    Xprofiler erases the current display and replaces it with only the function boxes for the function you chose, plus its parent functions.

There may be times when you may want to see the function boxes for both the parent and child functions of the function in which you are interested, without erasing the rest of the function call tree. This is especially true if you chose to display the function boxes for two or more of the most CPU-intensive functions with the Filter by CPU option of the Filter menu (you suspect that more than one function is consuming too much CPU). To do this:

  1. Place your mouse cursor over the function box in which you are interested, and press the right mouse button. The Function menu appears.
  2. From the Function menu, select the Immediate Parents option, and then the Add Parent Functions to Tree option.

    Xprofiler leaves the current display as it is, but adds the parent function boxes.

  3. Place your mouse cursor over the same function box and press the right mouse button. The Function menu appears.
  4. From the Function menu, select the Immediate Children option, and then the Add Child Functions to Tree option.

    Xprofiler leaves the current display as it is, but now adds the child function boxes in addition to the parents.

Clustering libraries together

When you first bring up the Xprofiler window, by default, the function boxes of your executable, and the libraries associated with it, are clustered. Since Xprofiler shrinks the call tree of each library when it places it in a cluster, you will need to uncluster the function boxes if you want to look closely at a specific function box label.

It is important to understand that you can see significantly more detail per function, when your display is in the unclustered or expanded state, than when it is in the clustered or collapsed state. So, depending on what you want to do, you will need to cluster or uncluster (collapse or expand) the display.

There may be times when the Xprofiler window is visually crowded. This is especially true if your application calls functions that are within shared libraries; function boxes representing your executable functions as well as the functions of the shared libraries get displayed. As a result, you may want to organize what you see in the Xprofiler window so you can focus on the areas that are most important to you. One way you can do this is to collect all the function boxes of each library into a single area, known as a library cluster.

When you choose to cluster your libraries, Xprofiler gathers all the functions for each one into a single area, and draws a green box around them. This is known as a cluster box. The name of the library also appears below the box.

The function boxes in the application shown in Figure 7 have been clustered. Note that one cluster box holds the function boxes associated with the executable hello_world, while the other cluster box holds the function boxes of the shared library /lib/profiled/libc.a:shr.o.

The example below shows the same application, hello_world, with its function boxes unclustered. Now that the function boxes of your executable and its shared libraries are displayed together, which means their relationships are more apparent.

Figure 20. Xprofiler Window with Function Boxes Unclustered
View figure.

Clustering functions

If the functions within your application are unclustered, you can use an option of the Filter menu to cluster them.

  1. Select the Filter menu, and then the Cluster Functions by Library option. The libraries within your application appear within their respective cluster boxes.

Once you cluster the functions in your application, as shown in Figure 7, you can further reduce the size (also referred to as collapse) of each cluster box. To do this:

  1. Place your mouse cursor over the edge of the cluster box and press the right mouse button. The Cluster Node Menu appears.
  2. Select the Collapse Cluster Node option. The cluster box, and its contents, now appear as a small solid green box. In the example below, the library /lib/profiled/libc.a:shr.o is collapsed.

Figure 21. Xprofiler Window with One Library Cluster Box Collapsed
View figure.

To return the cluster box to its original condition (expand it):

  1. Place your mouse cursor over the collapsed cluster box and press the right mouse button. The Cluster Node Menu appears.
  2. Select the Expand Cluster Node option. The cluster box, and its contents, appear once again.

Unclustering functions

If the functions within your application are clustered, you can use an option of the Filter menu to uncluster them.

  1. Select the Filter menu, and then the Uncluster Functions option. The cluster boxes disappear and the functions boxes of each library expand to fill the Xprofiler window.

If your functions have been clustered, you may want to remove one or more (but not all) cluster boxes. For example, say you wanted to uncluster only the functions of your executable, but keep its shared libraries within their cluster boxes. You would:

  1. Place your mouse cursor over the edge of the cluster box that contains the executable and press the right mouse button. The Cluster Node Menu appears.
  2. Select the Remove Cluster Box option. The cluster box disappears and the function boxes and call arcs, that represent the executable functions, now appear in full detail. The function boxes and call arcs of the shared libraries remain within their cluster boxes, which now appear smaller to make room for the unclustered executable function boxes.

The example below shows the executable, hello_world with its cluster box removed. Its shared library, /lib/profiled/libc.a:shr.o, remains within its cluster box.

Figure 22. Xprofiler Window with One Library Cluster Box Removed
View figure.

Locating specific objects in the function call tree

If you are interested in one or more specific functions in a complex program, you may need help locating their corresponding function boxes in the function call tree.

If you would like to locate a single function, and you know its name, you can use the Locate Function By Name option of the Utility menu. To locate a function by name:

  1. Select the Utility menu, and then the Locate Function By Name option. The Search By Function Name Dialog window appears.
  2. Type the name of the function you wish to locate in the Enter Function Name field. The function name you type here must be a continuous string (it cannot include blanks).
  3. Press the OK or Apply button. The corresponding function box is highlighted (its color changes to red) in the function call tree and Xprofiler zooms in on its location.

    To display the function call tree in full detail again, go to the View menu and use the Overview option.

There may also be times when you want to see only the function boxes for the functions you are concerned with, plus other specific functions that are related to it. For instance, suppose you want to see all the functions that directly called the function in which you are interested. It might not be easy to pick out these function boxes when you view the entire call tree, so you would want to display them, plus the function of interest, alone.

Each function has its own menu, called a Function menu. Via the Function menu, you can choose to see the following for the function in which you are interested:

When you use these options, Xprofiler erases the current display and replaces it with only the function boxes for the function of interest and all the functions of the type you specified.

Locating and displaying parent functions

A parent is any function that directly calls the function in which you are interested. To locate the parent function boxes of the function in which you are interested:

  1. Click on the function box of interest with the right mouse button. The Function menu appears.
  2. From the Function menu, select Immediate Parents>Show Parent Functions Only. Xprofiler redraws the display to show you only the function boxes for the function of interest and its parent functions.

Locating and displaying child functions

A child is any function that is directly called by the function in which you are interested. To locate the child functions boxes for the function in which you are interested:

  1. Click on the function box of interest with the right mouse button. The Function menu appears.
  2. From the Function menu, select Immediate Children>Show Child Functions Only. Xprofiler redraws the display to show you only the function boxes for the function of interest and its child functions.

Locating and displaying ancestor functions

An ancestor is any function that can call, directly or indirectly, the function in which you are interested. To locate the ancestor functions:

  1. Click on the function box of interest with the right mouse button. The Function menu appears.
  2. From the Function menu, select All Paths To>Show Ancestor Functions Only. Xprofiler redraws the display to show you only the function boxes for the function of interest and its ancestor functions.

Locating and displaying descendant functions

A descendant is any function that can be called, directly or indirectly, by the function in which you are interested. To locate the descendant functions (all the functions that the function of interest can reach, directly or indirectly):

  1. Click on the function box of interest with the right mouse button. The Function menu appears.
  2. From the Function menu, select All Paths From>Show Descendant Functions Only. Xprofiler redraws the display to show you only the function boxes for the function of interest and its descendant functions.

Locating and displaying functions on a cycle

To locate the functions that are on the same cycle as the function you are interested in:

  1. Click on the function of interest with the right mouse button. The Function menu appears.
  2. From the Function menu, select All Functions on the Cycle>Show Cycle Functions Only. Xprofiler redraws the display to show you only the function of interest and all the other functions on its cycle.

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]