23.4 Selecting what to profile

The Profiler's Set Profiling Parameters dialog

Choosing Profiler > Set Profiling Parameters... or clicking the Set Up Profiler toolbar button allows you to select what is shown in the profiler, as for the function hcl:set-up-profiler described in the LispWorks® User Guide and Reference Manual.

You can select values for keyword arguments of set-up-profiler:

Select packages	`:packages`
Select symbols	`:symbols`
Interval	`:interval`
Profile GC code	`:gc`
Call Counter	`:call-counter`
Show unknown frames	`:show-unknown-frames`
Select KW contexts	`:kw-contexts`

You cannot click OK in the dialog until you select at least one package, symbol or KW context.

Note that "symbols" are actually function dspecs (see "Function dspecs" in the LispWorks® User Guide and Reference Manual), so can also be setf functions and method names. KW contexts can be profiled only when KnowledgeWorks is loaded.

Once you click the OK button, hcl:set-up-profiler is called with the keywords listed above and the values that you have selected. See the documentation for hcl:set-up-profiler for details.

The effect of hcl:set-up-profiler is global and persistent, that is any profile operation in the same session (including any calls to hcl:profile and hcl:start-profiling) will use the settings from the last call to hcl:set-up-profiler. Thus using Set Profiling Parameters... and calling hcl:set-up-profiler will have the same effect.

Typically it is only useful to select packages (and if you use KnowledgeWorks, maybe KW contexts). If you want to select symbols, it is easier to type them in an editor, or write a function that computes the list, and then calls hcl:set-up-profiler explicitly.

In the packages selection, checking All or None passes the keyword :all or :none respectively as the value of :packages. Checking Selected passes a list of packages, which you can choose by clicking the "Choose packages.." button. When Selected is checked, if no package is chosen, the dialog for choosing packages is raised immediately. In the Select KW contexts selection, checking All passes t as the value of :kw-contexts.

23.4.1 Choosing the functions to profile

It is possible to keep track of every function called when running code, but this involves significant effort in determining which functions are suitable for profiling and in keeping track of the results. To minimize this effort you should specify which functions you want to profile. The profiler checks that these functions have indeed got function definitions and are therefore suitable for profiling. For more information on the types of function that can be profiled, see 23.8 Profiling pitfalls.

There are two ways of specifying functions that you want to profile:

Choose which individual functions you want to profile.
Choose whole packages, all of whose functions are profiled.

23.4.1.1 Choosing individual functions

Click the button to the right of Select symbols to specify a list of Lisp functions that you want to profile. The dialog shown in Select Symbols to Profile dialog appears.

Select Symbols to Profile dialog

This dialog displays the list of functions to be profiled.

To add a function to the list, enter its name in the New Symbol text box and click .
To remove a function from the list, select it from the list and click Remove.
To remove several functions, select them all before clicking Remove.

Click OK when you have finished choosing symbols.

Note: while entering the function name in the New Symbol text box you can click click to use completion. This allows you to select from a list of all symbol names which begin with the partial input you have entered. See 3.14 Completion for detailed instructions.

23.4.1.2 Choosing packages

You may often want to profile every function in a package, or if you do not know which symbols to profile, you will want profile all symbols in all packages.

You can select which packages to profile using the buttons in the Select packages area. Check the All button, which is initial setting, to profile all symbols in all packages. Check the None button if you only want to select specific symbols to profile. Check the Selected button if you want to choose specific packages to profile, which will display a dialog as shown in Select Packages to Profile dialog. If Selected is already checked, then click the Choose packages button to change the selected packages.

Select Packages to Profile dialog

The main part of this dialog consists of two lists:

The Unselected Packages list shows packages in the Lisp image whose functions are not to be profiled.
The Selected Packages list shows packages in the Lisp image whose functions are to be profiled.

A global function will be profiled if its symbol is visible in one of the selected packages.

To modify the Selected Packages list:

Consider whether one of these buttons offers what you need, or close to it:

All	Selects all packages. Note: There are significant processing overheads when profiling all functions in all packages, and the results you get may include much unwanted information.
User Only	Adds the "user" packages, which means packages that are not part of the LispWorks implementation, or packages that are part of the implementation but you are allowed to add definitions to them. Includes the CL-USER package.
User and CL	Adds the "user" and CL packages.
User and Standard	Adds the "user" packages along with those packages that are used by default (from the value of hcl:default-package-use-list, which initially includes CL, HCL and LW). Note: The Profiler tool assumes that packages not named in the value of packages-for-warn-on-redefinition are user-defined.

Add to your Selected Packages list if necessary. You can add a single package in one of three ways:
- Type the package name in the Select Package box and press Return or click , or:
- Select the package in the Unselected Packages list and click on the >>> button, or:
- Double-click on the package in the Unselected Packages list.
Remove packages from the Selected Packages list if necessary. You can remove a single package in one of two ways:
- Select the package in the Selected Packages list and click on the <<< button, or:
- Double-click on the package in the Selected Packages list.
  Also you can click the None button to clear the list of selected packages. Note that if you only want to profile a few functions, you should do this by checking the None button in the main dialog and selecting symbols as described in 23.4.1.1 Choosing individual functions.
Finally, click OK to dismiss the dialog when you have finished selecting the packages whose functions you want to profile, or click Cancel to cancel the operation. This also dismisses the dialog.