# Using Function Order Lists, Function Grouping, Function Ordering, and Data Ordering Optimizations

Instead of doing a full multi-file interprocedural build of your application by using the compiler option [Q]ipo, you can obtain some of the benefits by having the compiler and linker work together to make global decisions about where to place the functions and data in your application. These optimizations are not supported on macOS* systems.

The following table lists each optimization, the type of functions or global data it applies to, and the operating systems and architectures that it is supported on.

Optimization | Type of Function or Data | Supported OS and Architectures
--- | --- | ---
Function Order Lists: Specifies the order in which the linker should link the non-static routines (functions) of your program. This optimization can improve application performance by improving code locality and reduce paging. Also see Comparison of Function Order Lists and IPO Code Layout. | extern functions procedures and library functions only (not static functions). | Windows: all Intel architectures Linux: not supported
Function Grouping: Specifies that the linker should place the extern and static routines (functions) of your program into hot or cold program sections. This optimization can improve application performance by improving code locality and reduce paging. ### Note This option will cause functions to be placed into the linker sections named ".text.hot" and ".text.unlikely." If you are using a custom linker script, you will need to specify memory placement for these sections. | extern functions and static functions only (not library functions). | Linux: IA-32 and Intel 64 architectures Windows: not supported
Function Ordering: Enables ordering of static and extern routines using profile information. Specifies the order in which the linker should link the routines (functions) of your program. This optimization can improve application performance by improving code locality and reduce paging. | extern functions and static functions only (not library functions) | Linux and Windows: all Intel architectures
Data Ordering: Enables ordering of static global data items based on profiling information. Specifies the order in which the linker should link global data of your program. This optimization can improve application performance by improving the locality of static global data, reduce paging of large data sets, and improve data cache use. | Static global data only | Linux and Windows: all Intel architectures

You can only use one of the function-related ordering optimizations listed above on each application. However, you can use the Data Ordering optimization with any one of the function-related ordering optimizations listed above, such as Data Ordering with Function Ordering, or Data Ordering with Function Grouping. In this case, specify the prof-gen option keyword globdata (needed for Data Ordering) instead of srcpos (needed for function-related ordering).

The following sections show the commands needed to implement each of these optimizations: function order list, function grouping, function ordering, and data ordering. For all of these optimizations, omit the [Q]ipo or equivalent compiler option.

## Generating a Function Order List (Windows)

This section provides an example of the process for generating a function order list. Assume you have a C++ program that consists of the following files: file1.cpp and file2.cpp. Additionally, assume you have created a directory for the profile data files called c:\profdata. You would enter commands similar to the following to generate and use a function order list for your Windows application.

1. Compile your program using the /Qprof-gen:srcpos option. Use the /Qprof-dir option to specify the directory location of the profile files. This step creates an instrumented executable.

   Example commands
   `icl /Femyprog /Qprof-gen=srcpos /Qprof-dir c:\profdata file1.cpp file2.cpp`

2. Run the instrumented program with one or more sets of input data. Change your directory to the directory where the executables are located. The program produces a .dyn file each time it is executed.

   Example commands
   `myprog.exe`

3. Before this step, copy all .dyn and .dpi files into the same directory. Merge the data from one or more runs of the instrumented program by using the profmerge tool to produce the pgopti.dpi file. Use the /prof_dir option to specify the directory location of the .dyn files.

   Example commands
   `profmerge /prof_dir c:\profdata`

4. Generate the function order list using the proforder tool. By default, the function order list is produced in the file proford.txt.

   Example commands
   `proforder /prof_dir c:\profdata /o myprog.txt`

5. Compile the application with the generated profile feedback by specifying the ORDER option to the linker. Use the /Qprof-dir option to specify the directory location of the profile files.

Example commands
`icl /Femyprog /Qprof-use /Qprof-dir c:\profdata file1.cpp file2.cpp /link -ORDER:@myprog.txt`

## Using Function Grouping (Linux)

This section provides a general example of the process for using the function grouping optimization. Assume you have a C++ program that consists of the following files: file1.cpp and file2.cpp. Additionally, assume you have created a directory for the profile data files called profdata. You would enter commands similar to the following to use a function grouping for your Linux application.

1. Compile your program using the -prof-gen option. Use the -prof-dir option to specify the directory location of the profile files. This step creates an instrumented executable.

   Example commands
   `icc -o myprog -prof-gen -prof-dir ./profdata file1.cpp file2.cpp`

2. Run the instrumented program with one or more sets of input data. Change your directory to the directory where the executables are located. The program produces a .dyn file each time it is executed.

   Example commands
   `./myprog`

3. Copy all .dyn and .dpi files into the same directory. If needed, you can merge the data from one or more runs of the instrumented program by using the profmerge tools to produce the pgopti.dpi file.

4. Compile the application with the generated profile feedback by specifying the -prof-func-group option to request the function grouping as well as the -prof-use option to request feedback compilation. Again, use the -prof-dir option to specify the location of the profile files.

Example commands
`icl /Femyprog file1.cpp file2.cpp -prof-func-group -prof-use -prof-dir ./profdata`

## Using Function Ordering

### Note

On Linux, the –prof-func-group option is on by default when –prof-use is selected.

Finer grain control over the number of functions placed into the hot region can be controlled with the -prof-hotness-threshold compiler option, see the command line reference for more details.

This section provides an example of the process for using the function ordering optimization. Assume you have a C++ program that consists of the following files: file1.cpp and file2.cpp, and that you have created a directory for the profile data files called c:\profdata (on Windows) or ./profdata (on Linux). You would enter commands similar to the following to generate and use function ordering for your application.

1. Compile your program using the -prof-gen=srcpos (Linux) or /Qprof-gen:srcpos (Windows) option. Use the [Q]prof-dir option to specify the directory location of the profile files. This step creates an instrumented executable.

   Operating System | Example commands
   --- | ---
   Linux | `icc -o myprog -prof-gen=srcpos -prof-dir ./profdata file1.cpp file2.cpp`
   Windows | `icl /Femyprog /Qprof-gen:srcpos /Qprof-dir c:\profdata file1.cpp file2.cpp`

2. Run the instrumented program with one or more sets of input data. Change your directory to the directory where the executables are located. The program produces a .dyn file each time it is executed.

   Operating System | Example commands
   --- | ---
   Linux | `./myprog`
   Windows | `myprog.exe`

3. Copy all .dyn and .dpi files into the same directory. If needed, you can merge the data from one or more runs of the instrumented program by using the profmerge tools to produce the pgopti.dpi file.

4. Compile the application with the generated profile feedback by specifying the [Q]prof-func-order option to request the function ordering, as well as the [Q]prof-use option to request feedback compilation. Again, use the [Q]prof-dir option to specify the location of the profile files.

Operating System | Example commands
--- | ---
Linux | `icpc -o myprog -prof-dir ./profdata file1.cpp file2.cpp -prof-func-order-prof-use`
Windows | `icl /Femyprog /Qprof-dir c:\profdata file1.cpp file2.cpp /Qprof-func-order /Qprof-use`

## Using Data Ordering

This section provides an example of the process for using the data order optimization. Assume you have a C++ program that consists of the following files: file1.cpp and file2.cpp, and that you have created a directory for the profile data files called c:\profdata (on Windows) or ./profdata (on Linux). You would enter commands similar to the following to use data ordering for your application.

1. Compile your program using the -prof-gen=globdata (Linux) or /Qprof-gen:globdata (Windows) option. Use the -prof-dir (Linux) or /Qprof-dir (Windows) option to specify the directory location of the profile files. This step creates an instrumented executable.

   Operating System | Example commands
   --- | ---
   Linux | `icc -o myprog -prof-gen=globdata -prof-dir ./profdata file1.cpp file2.cpp`
   Windows | `icl /Femyprog /Qprof-gen=globdata /Qprof-dir c:\profdata file1.cpp file2.cpp`

2. Run the instrumented program with one or more sets of input data. If you specified a location other than the current directory, change your directory to the directory where the executables are located. The program produces a .dyn file each time it is executed.

   Operating System | Example commands
   --- | ---
   Linux | `./myprog`
   Windows | `myprog.exe`

3. Copy all .dyn and .dpi files into the same directory. If needed, you can merge the data from one or more runs of the instrumented program by using the profmerge tools to produce the pgopti.dpi file.

4. Compile the application with the generated profile feedback by specifying the [Q]prof-data-order option to request the data ordering as well as the [Q]prof-use option to request feedback compilation. Again, use the [Q]prof-dir option to specify the location of the profile files.

   Operating System | Example commands
   --- | ---
   Linux | `icpc -o myprog -prof-dir ./profdata file1.cpp file2.cpp -prof-data-order-prof-use`
   Windows | `icl /Femyprog /Qprof-dir c:\profdata file1.cpp file2.cpp /Qprof-data-order/Qprof-use`

Parent topic: PGO Tools