All Manuals > LispWorks IDE User Guide > 23 The Profiler

23.2 Description of the Profiler

There are four tabs in the main body of the tool. The first three tabs (Call Tree, Cumulative and Stacked Tree) display the current profiler information in the tool in different ways. The fourth tab (Code To Profile), contains an editor-pane where you can type code and then profile it.

Note that the profiler information in the tool may come from various sources. It may be a result of profiling the code in the Code To Profile tab or choosing Profiler > Start Profiling... or it can be the result of importing profiler information using the items in the Profiler menu.

The Echo area allows interaction with editor commands, as in other tools.

The Profiler

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.

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 Show 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.

Choosing Show calls to allocation functions [inverted] shows an inverted tree where the allocation functions are the roots, making it easier to see where allocation happens.

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

The Profiler's Cumulative Results view

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

With a suitable profiler setup it also shows:

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 23.4 Selecting what to profile:

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

23.2.4 Stacked Tree

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 23.2.2 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 12.8 Basic Editor commands.

Code may be placed in this window in three ways:

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 3.7.1 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 23.3 The Profiler menu and Profiler-specific toolbar buttons.

By default, the Profiler switches to the Stacked Tree tab after profiler finishes. You can change this using the buttons under When Code To Profile finishes profiling in the Profiler Preferences (see 23.7 Configuring the Profiler).


LispWorks IDE User Guide (Macintosh version) - 01 Dec 2021 19:36:36