inline

Applies to C Applies to C++

Purpose

Attempts to inline functions instead of generating calls to those functions. Inlining is performed if possible but, depending on which optimizations are performed, some functions might not be inlined.

Syntax

        .-noinline-----------------------.
>>- -q--+-inline--+--------------------+-+---------------------><
                  +-=threshold=num-----+
                  |          .-:-----. |
                  |          V       | |
                  '-+- + -+----names-+-'
                    '- - -'
 
 

Applies to C The following -qinline options apply in the C language:


-qinline The compiler attempts to inline all appropriate functions with 20 executable source statements or fewer, subject to any other settings of the suboptions to the -qinline option. If -qinline is specified last, all functions are inlined.
-qinline=threshold=num Sets a size limit on the functions to be inlined. The number of executable statements must be less than or equal to num for the function to be inlined. num must be a positive integer. The default value is 20. Specifying a threshold value of 0 causes no functions to be inlined except those functions marked with the __inline, _Inline, or _inline keywords.

The num value applies to logical C statements. Declarations are not counted, as you can see in the example below:

increment()
{
  int a, b, i;
   for (i=0; i<10; i++) /* statement 1 */
   { 
      a=i;              /* statement 2 */ 
      b=i;              /* statement 3 */
   } 
}
-qinline-names The compiler does not inline functions listed by names. Separate each name with a colon (:). All other appropriate functions are inlined. The option implies -qinline.

For example:

-qinline-salary:taxes:expenses:benefits

causes all functions except those named salary, taxes, expenses, or benefits to be inlined if possible.

A warning message is issued for functions that are not defined in the source file.

-qinline+names Attempts to inline the functions listed by names and any other appropriate functions. Each name must be separated by a colon (:). The option implies -qinline.

For example,

-qinline+food:clothes:vacation

causes all functions named food, clothes, or vacation to be inlined if possible, along with any other functions eligible for inlining.

A warning message is issued for functions that are not defined in the source file or that are defined but cannot be inlined.

This suboption overrides any setting of the threshold value. You can use a threshold value of zero along with -qinline+names to inline specific functions. For example:

-qinline=threshold=0

followed by:

-qinline+salary:taxes:benefits

causes only the functions named salary, taxes, or benefits to be inlined, if possible, and no others.

-qnoinline Does not inline any functions. If -qnoinline is specified last, no functions are inlined.

Applies to C++ The following -qinline options apply to the C++ language:


-qinline Compiler inlines all functions that it can.
-qnoinline Compiler does not inline any functions.

Default

The default is to treat inline specifications as a hint to the compiler, and the result depends on other options that you select:

Notes

The -qinline option is functionally equivalent to the -Q option.

If you specify the -g option (to generate debug information), inlining may be affected. See the information for the -g compiler option.

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

Normally, application performance is optimized if you request optimization (-O option), and compiler performance is optimized if you do not request optimization.

To maximize inlining, specify optimization (-O) and also specify the appropriate -qinline options.

The XL C/C++ (inline, _inline, _Inline, and __inline) C language keywords override all -qinline options except -qnoinline. The compiler will try to inline functions marked with these keywords regardless of other -qinline option settings.

The inline, _Inline, _inline, and __inline Function Specifiers

The compiler provides a set of keywords that you can use to specify functions that you want the compiler to inline. The keywords, which are functionally equivalent, are:

For example:

_Inline int catherine(int a);

suggests to the compiler that function catherine be inlined, meaning that code is generated for the function, rather than a function call.

Using the inline specifiers with data or to declare the main() function generates an error.

By default, function inlining is turned off, and functions qualified with inline specifiers are treated simply as extern functions. To turn on function inlining, specify either the -qinline or -Q compiler options. Inlining is also turned on if you turn optimization on with the -O or -qoptimize compiler option.

Recursive functions (functions that call themselves) are inlined for the first occurrence only. The call to the function from within itself is not inlined.

You can also use the -qinline or -Q compiler options to automatically inline all functions smaller than a specified size. For best performance, however, use the inline keywords to choose the functions you want to inline rather than using automatic inlining.

An inline function can be declared and defined simultaneously. If it is declared with one of the inline keywords, it can be defined without any inline keywords. The following code fragment shows an inline function definition. Note that the inline keywords are specified for both a function definition and function declaration.

_inline int add(int i, int j) { return i + j; }
 
inline double fahr(double t);
Note:
The use of the inline specifier does not change the meaning of the function, but inline expansion of a function may not preserve the order of evaluation of the actual arguments.

Example

To compile myprogram.C so that no functions are inlined, enter:

xlc++ myprogram.C -O -qnoinline

To compile myprogram.c so that the compiler attempts to inline functions of fewer than 12 lines, enter:

xlc myprogram.c -O -qinline=12

Related references

IBM Copyright 2003