18    Profiler

This chapter provides an overview of the Profiler's features and capabilities. For more detailed information on how to use this tool, choose Help: On Profiler. You can print Help topics using the HyperHelp Viewer.

The FUSE Profiler gathers and analyzes run-time statistics on your program, such as performance and resource use information. The Profiler provides a graphical user interface from which you can generate profiling data for a program and view the data in graph or text format.

The Profiler can use any of the following utilities to perform its generation and analysis: pixie, hiprof, prof, and gprof.

Figure Figure 18-1 shows the Profiler main window.

Figure 18-1:  Profiler Main Window

Key elements are the major window panes running from the top to the bottom of the window:

Configuration area

Displays the current project, working directory, target executable file, and directory in which the profiling data is stored.

Setup area

Lets you specify the criteria to use when generating data.

Display area

Shows either your program's input and output or data generated by the Profiler.

Information area

Displays information messages and Quick Help on menu items when you press and hold MB1 on the item.

The types of data the Profiler generates and displays depends on which profiling utility the Profiler uses, which options you use to compile and link your program, and the platform on which you are running the Profiler.

18.1    Summary of Features

The Profiler does the following:

• Provides a graphic, integrated interface to pixie, hiprof, prof, and gprof.

• Executes your program to generate run-time statistics.

• Displays and reviews run-time statistics in histogram format.

• Displays the source associated with run-time statistics through integration with editors.

• Provides analysis of multithreaded applications.

18.2    Requirements for Using the Profiler

To use the Profiler for generating and displaying profiling data, make sure that:

• A working executable file of the target program is available as specified in the Project Manager. The Profiler runs the executable file to generate profiling data. If the executable file has run-time errors, no profiling data will be generated.

• The prof utility, or a link to the prof utility, is in /usr/bin.

• The Atom tools, gprof, prof and pixie utilities are available on your system. See your system manager if necessary.

18.3    Compiling Your Program

Before you can get profiling data on your program using the Profiler, you must first compile and link your program to specify the profiling utility you want to use. Refer to the online Help for additional information about compiling your program.

18.4    Starting the Profiler

After you compile and link your program, you are ready to start the Profiler and then generate and view run-time analysis data. You can start the Profiler in several ways:

• Use the command line.

• If you have CDE installed, use the Profiler icon.

• Use the FUSE Control Panel once FUSE is running.

• Use the Tools menu from most FUSE tools.

18.4.1    Use the Command Line

To start the Profiler from the command line, use the following command:

% fuseprof [-cwd] [-data directory-path] [Xt-options] [target]

See Appendix Appendix D and the specific reference pages for the command syntax and options.

If the Control Panel is not running, it starts automatically as a minimized icon. If FUSE is already running, the Profiler is placed in the current project.

18.4.2    Use the Profiler Icon from CDE

When you have CDE installed, FUSE provides a FUSE application group icon and icons for the individual tools that make up the FUSE environment.

To invoke the Profiler:

1. Double click on the Application Manager icon in the CDE Front Panel to display the application group icons.

2. Double click on the FUSE application group icon to display the icons in the FUSE application group.

3. Double click on the Profiler icon to start the tool.

18.4.3    Use the FUSE Control Panel

To start the Profiler from the FUSE Control Panel:

1. Select Profiler from the Tools menu in the Control Panel.

   The Profiler needs a working directory and target executable to start. The target executable is the program for which the Profiler will generate and display profiling data.

   Like all FUSE tools, the Profiler inherits its configuration data from the project settings. If these settings are already specified, the Profiler main window appears.

2. If you haven't already specified a target executable, an informational box prompts you to specify one. Click OK in this box to display the Project Manager for setting project configuration settings.

3. In the Project Manager, enter the target executable in the Executable Target field.

4. Optionally, enter a Data Directory, which the Profiler will use to store the profiling data. (This data directory is also used by the Heap Analyzer to store memory analysis data.) By default, this is the same as the working directory. Enter a directory name only if you want to change it from the working directory.

5. Optionally, enter a directory name in the New Source Directory text field to be added to the Source Directory List. These directories are checked for source files if the Profiler (and Builder, Debugger, and Heap Analyzer) cannot find the files initially. Enter new directory names one at a time in the text field, then use the Add button to add them to the Source Directory List. Use the Remove button to remove names.

6. Click OK in the Project Manager and the Profiler main window appears.

18.4.4    Use the Tools Menu from Most FUSE Tools

Most FUSE tools have a Tools menu. To start a tool, select the tool from the Tools menu.

18.5    Profiling Actions

The Profiler is always in one of two modes of action:

• Generating data

• Showing data

Use the Action options menu in the Profiler main window to choose which action you want:

18.5.1    Generate Data Action

Figure Figure 18-2 shows the display area when the Generate Data action is selected. Table Table 18-1 lists the additional components of the window that are displayed for this action.

Figure 18-2:  Profiler Window with Generate Data Action Selected

Table 18-1:  Window Components for the Generate Data Action

Component	Description
Setup... button	Click on this button to bring up a dialog box to specify the criteria to use when generating data.
Create Unique Data Files Per Run check box	Check this box if you want the process ID to be included in each data file name so that each data file is unique. Every data file created is added to the list of data files instead of replacing an old data file.
Collect Separate Data For Each Thread check box	Check this box if you want data to be collected for each thread in a multithreaded application.
Optional Arguments for Target field	When the Profiler runs your program to generate data, it invokes the program using the information you specify here. Use this field to enter any command-line arguments that the program requires as you would in a terminal window using your shell. You can use environment variables, quoted strings, and I/O redirection as youwould in your shell.
Tool Options... button	Click on this button to set options for the analysis utility you are using. This button is available only with those utilities that have options.
Run/Stop Run button	Click on the Run button to run the executable file and generate profiling data. When you click on Run, this button automatically changes to Stop Run, allowing you to stop the execution of your program. If you click on Stop Run, the Profiler does not generate a valid profiling data file. It may modify your application depending on when you click on the Stop button.
Target's Input/Output:	When you click on the Run button to generate profiling data, this area shows the output from the target program and displays any request for input from the program. You can enter program input directly in this area.

For more information on how to generate data, choose Help: On Profiler or Help: FUSE Tutorials from the Profiler.

18.5.2    Show Data Action

Figure Figure 18-3 shows the display area when the Show Data action is selected. Table Table 18-2 lists the additional window components that are displayed for this action.

Figure 18-3:  Profiler Window with Show Data Action Selected

Table 18-2:  Window Components for the Show Data Action

Component	Description
Setup... button	Click on this button to bring up a dialog box to specify the criteria to use when showing data.
Filters... button	Click on this button to bring up a dialog box to control which items are filtered from the display when showing data.
Show options menu	Click on this menu to choose the type of data you want to display.
As options menu	Click on this menu to choose the display format for the analysis data selected in the Show options box. See Table Table 18-5 for a description of display formats.
Data File(s) field	This field shows the data file or files from which profiling data has been generated. You can enter multiple names in this field, separated by spaces, and can use wildcards. Use the Pick... button to browse for files.
Display Data From options menu	Click on this menu to choose how to display data for multithreaded applications.
Apply button	Click on this button to display the profiling data.
Display area	This area shows the currently selected profiling data.

18.6    Types of Statistics Displayed by the Profiler

Table Table 18-3 shows the types of statistics displayed by the Profiler.

Table 18-3:  Types of Statistics Displayed by the Profiler

When you choose the following statistic...	Profiler displays...
Functions by CPU Cycles	The percentage of CPU cycles spent in each function during program execution, not including cycles spent in called functions.
Lines by CPU Cycles	The percentage of CPU cycles spent in each function for each line in a selected function.
Functions by Calls	The number of times each function was called.
Functions by Time	The number of CPU seconds spent in each function, not including cycles spent in called functions.
Function Coverage	The names of functions that were never called.
Line Coverage	The number of lines never executed in a function.
Instructions by CPU Cycles	The percentage of CPU cycles spent in each instruction.
Cumulative Functions by CPU Cycles	The percentage of CPU cycles spent in each function, including time spent in each function called by that function.
Cumulative Functions by Time	The number of CPU seconds spent in each function, including seconds spent in each function called by that function.

Table Table 18-4 shows the types of statistics supported by the profiling utilities.

Table 18-4:  Types of Statistics Supported by Profiling Utilities

Utility	Supported Statistics
pixie	Functions by CPU Cycles Lines by CPU Cycles Functions by Calls Functions by Time Function Coverage Line Coverage Instructions by CPU Cycles
hiprof	Functions by CPU Cycles Functions by Calls Functions by Time Function Coverage Cumulative Functions by CPU Cycles Cumulative Functions by Time
prof	Functions by CPU Cycles Functions by Time
gprof	Functions by CPU Cycles Functions by Calls Functions by Time Cumulative Functions by CPU Cycles Cumulative Functions by Time

18.7    Display Formats

Depending on which utility you compile and link your program with, the Profiler produces the display formats shown in Table Table 18-5.

Table 18-5:  Profiler Display Formats

Utility	Format	Description
pixie         hiprof         prof         gprof	Text	Displays the data as simple text in a chart format
pixie         hiprof         prof         gprof	Simple histogram	Displays the data as a histogram, typically with the function, register, or instruction in the left column and the display values in the right column.
pixie         hiprof         gprof	2-level histogram	Displays the data as a histogram similar to the simple histogram. If you double click on an entry in the display, the Profiler displays additional information. Double click again to return to the simple histogram format.
All utilities	Program Visualizer	Displays the data using the FUSE Program Visualizer.
pixie         hiprof         gprof	Calls	Displays, in histogram format, all calls made to and all calls made from a selected function.

18.8    Showing More Detailed Information

If you have compiled and linked your program with pixie, hiprof, or gprof, the Profiler can display 2-level histograms of some statistics:

Double click again to toggle back to the function display.

You can press MB2 on a line in the graph to start the FUSE Editor and display the source code for the line. The Profiler places a colored icon in the Editor annotation area next to the referenced line.