-qinline

Category

Optimization and tuning

Pragma equivalent

None.

Purpose

Attempts to inline functions instead of generating calls to those functions, for improved performance.

Syntax

Read syntax diagramSkip visual syntax diagram
>>-+- -qinline-+----------------------------+-+----------------><
   |           |   .-:--------------------. | |   
   |           |   V                      | | |   
   |           +-=---+-auto-------------+-+-+ |   
   |           |     +-noauto-----------+   | |   
   |           |     +-level--=--number-+   | |   
   |           |     '-autothreshold----'   | |   
   |           |         .-:-------------.  | |   
   |           |         V               |  | |   
   |           '-+- + +----function_name-+--' |   
   |             '- - '                       |   
   '- -qnoinline------------------------------'   

Defaults

If -qinline is not specified, the default option is -qnoinline at the -O0 or -qnoopt optimization level or -qinline=noauto:level=5 at the -O2 or higher optimization levels.

If -qinline is specified without any suboptions, the default option is -qinline=auto:level=5.

Parameters

noauto | auto
Enables or disables automatic inlining.
level=number
Represents the relative degree of inlining. The values for number must be positive integers from 0 to 10 inclusive. The default value for number is 5. The greater the value of number, the more aggressive inlining the compiler conducts.
autothreshold
Represents the largest number of executable statements that a function can include when the function is to be inlined. The value for autothreshold must be a positive integer. The default value for autothreshold is 20. If you specify a value of 0, only functions that are specified with the IBM only beginsalways_inline or __always_inline__ attributeIBM only ends or specified after -qinline+ are inlined. In the following example, three executable statements are included in the increment function. 
int increment(){
  int a, b, i;
  for (i=0; i<10; i++){   // statement 1
    a=i;                  // statement 2
    b=i;                  // statement 3  
  } 
}
function_name
If the function_name is specified after the -qinline+ option, the named function must be inlined. If the function_name is specified after the -qinline- option, the named function must not be inlined.

Usage

You can specify -qinline with any optimization level of -O2, -O3, -O4, or -O5 to enable inlining of functions, including those functions that are declared with the inline specifier.

When -qinline is in effect, the compiler determines whether inlining a specific function can improve performance. That is, whether a function is appropriate for inlining is subject to two factors: limits on the number of inlined calls and the amount of code size increase as a result. Therefore, enabling inlining a function does not guarantee that function will be inlined.

Because inlining does not always improve runtime performance, you need to test the effects of this option on your code. Do not attempt to inline recursive or mutually recursive functions.

You can use the -qinline+<function_name> or -qinline-<function_name> option to specify the functions that must be inlined or must not be inlined.

IBM only beginsThe -qinline-<function_name> option takes higher precedence than the always_inline or __always_inline__ attribute. When you specify both the always_inline or __always_inline__ attribute and the -qinline-<function_name> option to a function, that function is not inlined.IBM only ends

Specifying -qnoinline disables all inlining, including that achieved by the high-level optimizer with the -qipa option, and functions declared explicitly as inline. However, the -qnoinline option does not affect the inlining of the following functions:
  • IBM only beginsFunctions that are specified with the always_inline or __always_inline__ attributeIBM only ends
  • Functions that are specified with the -qinline+<function_name> option

If you specify the -g option to generate debugging information, the inlining effect of -qinline might be suppressed.

If you specify the -qcompact option to avoid optimizations that increase code size, the inlining effect of -qinline might be suppressed.

Note:
  • -qinline replaces -Q and its suboptions.
  • -Q, -Q!, -Q=threshold, -Q+name, and -Q-name are all deprecated options and suboptions.
  • -qipa=inline and all of its associated suboptions are deprecated. -qinline replaces them all.

Predefined macros

None.

Examples

Example 1
To compile myprogram.c so that no functions are inlined, use the following command: 
xlc myprogram.c -O2 -qnoinline

However, if some functions in myprogram.c are specified with the IBM only beginsalways_inline or __always_inline__ attributeIBM only ends, the -qnoinline option has no effect on these functions and they are still inlined.

If you want to enable automatic inlining, you use the auto suboption: 
-O2 -qinline=auto
You can specify an inlining level 6 - 10 to achieve more aggressive automatic inlining. For example:
-O2 -qinline=auto:level=7
If automatic inlining is already enabled by default and you want to specify an inlining level of 7, you enter:
-O2 -qinline=level=7
Example 2
Assuming myprogram.c contains the salary, taxes, expenses, and benefits functions, you can use the following command to compile myprogram.c to inline these functions: 
xlc myprogram.c -O2 -qinline+salary:taxes:expenses:benefits
If you do not want the functions salary, taxes, expenses, and benefits to be inlined, use the following command to compile myprogram.c:
xlc myprogram.c -O2 -qinline-salary:taxes:expenses:benefits
You can also disable automatic inlining and specify certain functions to be inlined with the -qininline+ option. For example:
-O2 -qinline=noauto -qinline+salary:taxes:benefits
In this case, the functions salary, taxes, and benefits are inlined. Besides, functions that are specified with the IBM only beginsalways_inline or __always_inline__ attributeIBM only ends or declared with the inline specifier are also inlined. No other functions are inlined.
You cannot mix the + and - suboptions with each other or with other -qinline suboptions. For example, the following options are invalid suboption combinations:
-qinline+increase-decrease    // invalid
-qinline=level=5+increase     // invalid
However, you can use -qinline separately. For example:
-qinline+increase -qinline-decrease -qinline=noauto:level=5

Related information

Parent topic: Individual option descriptions