25.4 Steps involved in profiling code

Each time you profile code, you first need to set up the profiler to ensure that you find out the sort of information you are interested in. This section gives you details about how to go about this.

Note: You do not have to adhere strictly to the sequence shown above, but this is the order that you should usually follow.

See the chapter on the Profiler in the LispWorks User Guide and Reference Manual for information on advanced configuration of the profiler.

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

25.4.1.1 Choosing individual functions

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

Figure 25.4 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 Completion for detailed instructions.

25.4.1.2 Choosing packages

You may often want to profile every function in a package. Click Packages... to specify a list of packages whose functions you want to profile. The dialog shown in Select Packages to Profile dialog appears.

Figure 25.5 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. This is useful is you only want to profile a few functions, which you can specify easily using the Symbols... button on the Profiler tool itself.

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.

25.4.3 Specifying the code to run while profiling

Code which is to be executed during profiling should be entered in the Code to Profile area. This is actually an editor window, and so you can use all the keyboard commands which can be used in the editor.

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 Works > Tools > 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.