23.2.1 Call Tree

The Call Tree tab shows a graph of functions called by the top level function call that was profiled. Each node represents a function call. The graph edges are labelled according to the proportion of time spent in each function call. For example in The Profiler, of all the time spent in function bar, most was spent in baz and the rest in quux. This allows you to see which branches of the code dominate the total time spent.

When optimizing your code you will want to concentrate on the calls which take a large proportion of the time. The least significant parts of the graph are removed from the display according to the percentage in the Hide calls below (%) box. You can adjust this percentage simply by entering an integer and pressing Return.

When analysing the call tree to find the most significant branches, single callees (that is, functions which account for all of the time spent by their caller) are not interesting. You can adjust the call tree to omit these functions from the displayed graph by checking the Collapse singletons box.

A Description area optionally shows a description of a function in the profile data. You can show the description by clicking on the Description >> button. The name, function object, lambda list, documentation string and source files of the selected function are displayed. The context menu in the description area allows further operations. Hide the description area if you wish by clicking on the Description << button.

Figure 23.2 The Profiler's Call Tree adjusted

23.2.2 Options in the context menu for viewing parts of the call graph

The context menu in the Call Tree and the Stacked Tree tabs allow you to view a subset of the call tree in various ways based on the selected node.

Choosing Set Node As Root makes the selected node be the root of the displayed tree.

Choosing Set Function As Root makes the function associated with the selected node be the root of the displayed tree, by merging all subtrees starting at the outermost occurrences of that function. Nodes above the outermost occurrences are not displayed.

Note that the branches in the displayed tree for the selected function are merged across all branches in the whole tree for matching functions and caller chains. For example, suppose the profiler sometimes saw function A calling function V calling function W, (A>V>W), and at other times saw B>V>W>X, and other times saw C>V>Y>W. In the whole tree, each of these call chains will be on separate branches because they start with different functions (A, B and C). However, if you set the function V to be root of the tree, then underneath there will two children: one for W with a child X (merging the occurrences of V>W in A>V>W and B>V>W>X) and one for Y with a child W (for the occurrence of V>Y in C>V>Y>W.).

Choosing Calls To Function [Inverted] creates an inverted tree with the function at its root. The children of the inverted tree are the callers of that function and the branches are merged as for Set Function As Root tree. An inverted tree is a useful way for exploring why a function seems to be on the stack more than expected.

Choose Show Whole Tree to display the entire call tree again.

Notes: These menus items set new values in the panes (the roots in the graph of the Call Tree tab and root in the stacked tree of the Stacked Tree tab). They reset the history of scroll/zoom states in stacked tree. Using the History menu to move between trees always resets to the whole tree. Currently there is no history of subtree settings.

23.2.3 Cumulative Results

Figure 23.3 The Profiler's Cumulative Results view

The Cumulative tab shows aggregated information about each function that includes the following information:

• The number of times each function was found on the stack by the profiler, both in absolute terms and as a percentage of the total number of scans of the stack.
• The number of times each function was found on the top of the stack, both in absolute terms and as a percentage of the total number of scans of the stack.

With a suitable profiler setup it also shows:

• The number of times each function being profiled was called.

Note: by default the Profiler does not count function calls, because this can distort results significantly in SMP LispWorks. Therefore the Call# column shows 0 for each function. To make the Profiler count calls, check Call counter in the dialog described in Selecting what to profile:

The Filter box lets you restrict the display of information in the Results area.

23.2.4 Stacked Tree

Figure 23.4 The Profiler's Stacked Tree view

The results can also be displayed in capi:stack-tree pane. See the documentation for capi:stacked-tree for details on how it works in the general. This capi:stacked-tree displays the same tree as the graph in Call Tree . When the tree changes for any reason, both panes change to display the new tree. In particular, when using the context menu to display only part of the tree, both panes display the same part.

In the Stacked Tree tab, the root node represents the total for all processes. Note that when profiling more than one process, the percentage for all processes will typically be higher than 100%. The children of the root node are the processes that were profiled, which correspond to the root nodes in Call Tree tab.

The Stacked Tree in general is easier to navigate than the Call Tree because it is more compact and has useful options for zooming into specific regions.

The context menu in the Stacked Tree tab allow you to view a subset of the call tree in various ways based on the selected node, as described in Options in the context menu for viewing parts of the call graph.

A Description area optionally shows a description of a function in the profile data. You can show the description by clicking on the Description >> button. The name, function object, lambda list, documentation string and source files of the selected function are displayed. The context menu in the description area allows further operations. Hide the description area if you wish by clicking on the Description << button.

23.2.5 Code To Profile

Use the large text box in the Code To Profile tab to enter the Lisp source code that you wish to profile. This text area is actually an editor window, similar to those described in Basic Editor commands.

Code may be placed in this window in three ways:

• Type it directly into the window
• Paste it in from other editor windows in the environment
• Paste it in from other applications

Specify the package in which you want to run the code to be profiled using the Package box in the General tab of the Profiler Preferences. To see this, choose LispWorks > Preferences... or click , and select Profiler in the list on the left side of the dialog. If you are unsure, full details on how to do this can be found in Specifying a package. Like all other tools in the LispWorks IDE, the Profiler can have a particular package associated with it; the default package is CL-USER.

You can then profile it, using either by clicking the Profile toolbar button or the Profiler > Profile the 'Code To Profile' menu item. This reads one form from the text box, evaluates it while profiling and then displays the make the result the current profiler information in the tool.

Note: The Code To Profile tab only profiles the thread that is evaluating the form. It does not profile other threads. To profile multiple threads, choose Profiler > Start Profiling... as described in The Profiler menu and Profiler-specific toolbar buttons.