Dumping snapshot PDF profiling information during execution

Before you begin

Compile some or all of the source files in a program with the -qpdf1 option.

About this task

In addition to getting PDF profiling information that is written to one or more PDF files upon normal termination, you can dump PDF profiling information to one or more PDF snapshot files during execution. This is especially useful when the application is to be terminated abnormally, for example, when you end a process by using SIGKILL or a system call exit(), _Exit(), or abort().

Procedure

Define environment variable PDF_SIGNAL_TO_DUMP as a signal value that is an integer in the range of SIGRTMIN and SIGRTMAX inclusive. This value is read during program initialization.
Run the application that was generated in the PDF1 step.
Send the user-defined signal value as a trigger to dump PDF profiling information to PDF snapshot files. You can send the user-defined signal value multiple times for each process, and the corresponding PDF snapshot file is overwritten each time. The running application processes continue running until normal termination.

Results

A PDF snapshot file is created for each process with suffix _snapshot.<pid>, and it is named .<output_name>_pdf_snapshot.<pid> by default, where <output_name> is the name of the output file that is generated in the PDF1 step and <pid> is the ID of the process.

If the application creates more than one process, equivalent number of PDF data files are generated when each process receives the signal.

If multiple PDF snapshot files are generated, you must merge the PDF snapshot files for multiple processes by using the mergepdf command before linking or recompiling the program with -qpdf2.

If the application ends normally by executing exit handlers, a standard PDF file named .<output_name>_pdf is also generated.

Example

In this example, program myprogram has a parent process and a child process. You can dump snapshot PDF profiling information to files during execution and use the merged PDF file to fine-tune the optimizations as follows:

Compile myprogram.c with -qpdf1 and name the executable file as myprogram.
```
xlc -O2 -qpdf1 -o myprogram myprogram.c
```
Define environment variable PDF_SIGNAL_TO_DUMP as 52, which is in the range of SIGRTMIN and SIGRTMAX inclusive.
```
export PDF_SIGNAL_TO_DUMP=52
```
Run the compiled application.
```
./myprogram < sample.data &
```
The following process ID is displayed:
```
[138705]    ./myprogram &
```
Send the user-defined signal 52 to dump PDF profiling information by using the kill command.
Note: The kill command does not terminate the processes when the signal value is recognized.
```
kill -s 52 138705
```
Because the application creates a parent process and a child process, both processes receive the signal value. The following messages are displayed for both processes:
```
PDFRunTime: Caught user signal "52", dumping PDF data ... Done.
PDFRunTime: Caught user signal "52", dumping PDF data ... Done.
```
Two PDF snapshot files that are suffixed with process ID, .myprogram_pdf_snapshot.138705 and .myprogram_pdf_snapshot.138706, are created, where 138706 is a child process of 138705.
Merge PDF data for the two processes as .myprogram_pdf.
```
mergepdf .myprogram_pdf_snapshot.* -o .myprogram_pdf
```
Recompile myprogram.c by using the same compiler options as step 1, but change -qpdf1 to -qpdf2. .myprogram_pdf is used to fine-tune the optimizations.
```
xlc -O2 -qpdf2 -o myprogram myprogram.c
```

Voice your opinion on getting help information

Ask IBM compiler experts a technical question in the IBM XL compilers forum