INLINE | NOINLINE

Pragma equivalent

#pragma inline (C only), #pragma noinline

#pragma options (inline) (C only), #pragma options (noinline) (C only)

Purpose

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

When the INLINE compiler option is in effect, the compiler places the code for selected subprograms at the point of call; this is called inlining. It eliminates the linkage overhead and exposes the entire inlined subprogram for optimization by the global optimizer.

When the NOINLINE compiler option is in effect, the compiler generates calls to functions instead of inlining functions.

Syntax


   .-NOINL-.                                       
>>-+-INL---+--+--------------------------------+---------------->
              '-(--+--------+--,--+----------+-'   
                   +-AUTO---+     +-REPORT---+     
                   '-NOAUTO-'     '-NOREPORT-'     

>--+-----------------------------------+-----------------------><
   '-,--+-----------+--,--+-------+--)-'   
        '-threshold-'     '-limit-'

Defaults

For a C/C++ compile:

If NOOPT is in effect:
```
NOINLINE
  (AUTO,NOREPORT,
  100,1000)
```
If OPT is in effect:
```
INLINE
  (AUTO,NOREPORT,
  100,1000)
```

NOOPT is the default for C/C++ compile.

For IPA Link:

If NOOPT is in effect:
```
NOINLINE
  (AUTO,NOREPORT,
  1000,8000)
```
If OPT is in effect:
```
INLINE
  (AUTO,NOREPORT,
  1000,8000)
```

OPT is the default for IPA Link.

For the c99, c89, cc, and c++ z/OS® UNIX System Services utilities, the default is NOINLINE(AUTO,NOREPORT,,).

For the z/OS UNIX utilities, when NOOPT is specified, the default is NOINLINE(AUTO,NOREPORT,100,1000). When OPT is specified, the default is INLINE(AUTO,NOREPORT,100,1000).

In the z/OS UNIX environment, specifying -V, when using the c89 or cc commands, will turn on the REPORT suboption of INLINE. The INLINE option itself is not touched (or changed) by -V.

Parameters

Note: You can specify INLINE without suboptions if you want to use the defaults. You must include a comma between each suboption even if you want to use the default for one of the suboptions. You must specify the suboptions in the following order:

AUTO | NOAUTO

The inliner runs in automatic mode and inlines subprograms within the threshold and limit.

For C only, if you specify NOAUTO the inliner only inlines those subprograms specified with the #pragma inline directive. The #pragma inline and #pragma noinline directives allow you to determine which subprograms are to be inlined and which are not when the INLINE option is specified. These #pragma directives have no effect if you specify NOINLINE. See z/OS XL C/C++ Language Reference for more information on #pragma directives.

The default is AUTO.

REPORT | NOREPORT

An inline report becomes part of the listing file. The inline report consists of the following:

An inline summary
A detailed call structure

You can obtain the same report if you use the INLRPT and OPT options. For more information on the inline report, see Inline Report, Inline Report, and Inline Report for IPA inliner.

The default is NOREPORT.

threshold

The maximum relative size of a subprogram to inline. For C/C++ compiles, the default for threshold is 100 Abstract Code Units (ACUs). For the IPA link step, the default for threshold is 1000 ACUs. ACUs are proportional in size to the executable code in the subprogram; the z/OS XL C compiler translates your z/OS XL C code into ACUs. The maximum threshold is INT_MAX, as defined in the header file limits.h. Specifying a threshold of 0 is the same as specifying NOAUTO.

limit

The maximum relative size a subprogram can grow before auto-inlining stops. For C/C++ compiles, the default for limit is 1000 ACUs for a subprogram. For the IPA link step, the default for limit is 8000 ACUs for that subprogram. The maximum for limit is INT_MAX, as defined in the header file limits.h. Specifying a limit of 0 is equivalent to specifying NOAUTO.

Usage

The INLINE compiler option has the following effects:

The compiler invokes the compilation unit inliner to perform inlining of functions within the current compilation unit.
If the compiler inlines all invocations of a static subprogram, it removes the non-inlined instance of the subprogram.
If the compiler inlines all invocations of an externally visible subprogram, it does not remove the non-inlined instance of the subprogram. This allows callers who are outside of the current compilation unit to invoke the non-inlined instance.
If you specify INLINE(,REPORT,,) or INLRPT, the compiler generates the Inline Report listing section.

For more information on optimization and the INLINE option, refer to the section about optimizing code in the z/OS XL C/C++ Programming Guide.

You can specify the INLINE | NOINLINE option on the invocation line and for C in the #pragma options preprocessor directive. When you use both methods at the same time, the compiler merges the suboptions. If a suboption on the invocation line conflicts with a suboption in the #pragma options directive, the one on the invocation line takes precedence. If the NOINLINE option is specified on the invocation line and the #pragma options(inline) directive is used, the compiler will behave as if the INLINE option is specified. If the INLINE option is specified on the invocation line and the #pragma options(noinline) directive is used, the compiler will behave as if the INLINE option is specified.

For example, because you typically do not want to inline your subprograms when you are developing a program, you can use the #pragma options(noinline) directive. When you want to inline your subprograms, you can override the #pragma options(noinline) by specifying INLINE on the invocation line rather than by editing your source program. The following example illustrates these rules.

Source file:: #pragma options(noinline(noauto,noreport,,2000))
Invocation line:: INLINE (AUTO,,,)
Result:: INLINE (AUTO,NOREPORT,100,2000)

Notes:

When you specify the INLINE compiler option, a comment, with the values of the suboptions, is generated in your object module to aid you in diagnosing your program.
If the compiler option OPT is specified, INLINE becomes the default.
Specify the INLRPT, LIST, or SOURCE compiler options to redirect the output from the INLINE(,REPORT,,) option.
If you specify INLINE and TEST:
- at OPT(0), INLINE is ignored
- at OPT, inlining is done
If you specify NOINLINE, no subprograms will be inlined even if you have #pragma inline directives in your code.
If you specify INLINE, subprograms may not be inlined or inline other subprograms when COMPACT is specified (either directly or via #pragma option_override). Generate and check the inline report to determine the final status of inlining. The inlining may not occur when OPT(0) is specified via the #pragma option_override.
A virtual function might not be inlined even when the function is specified with the always_inline attribute. No informational message is issued when a virtual function is not inlined.

IPA effects

The INLINE option generates inlined code for the regular compiler object; therefore, it affects the IPA compile step only if you specify IPA(OBJECT). If you specify IPA(NOOBJECT), INLINE has no effect, and there is no reason to use it.

If you specify the INLINE option on the IPA link step, it has the following effects:

The IPA link step invokes the IPA inliner, which inlines subprograms (functions and C++ methods) in the entire program.
The IPA link step uses #pragma inline | noinline directive information and inline subprogram specifier information from the IPA compile step for source program inlining control. Specifying the INLINE option on the IPA compile step has no effect on IPA link step inlining processing.
You can use the IPA Link control file inline and noinline directives to explicitly control the inlining of subprograms on the IPA link step. These directives override IPA compile step #pragma inline | noinline directives and inline subprogram specifiers.
If the IPA link step inlines all invocations of a subprogram, it removes the non-inlined instance of the subprogram, unless the subprogram entry point was exported using a #pragma export directive or the EXPORTALL compiler option, or was retained using the IPA Link control file retain directive. IPA Link processes static subprograms and externally visible subprograms in the same manner.

The IPA inliner has the inlining capabilities of the compilation unit inliner. In addition, the IPA inliner detects complex recursion, and may inline it. If you specify the INLRPT option, the IPA Link listing contains the IPA Inline Report section. This section is similar to the report that the compilation unit inliner generates. If you specify NOINLINE(,REPORT,,) or NOINLINE INLRPT, IPA generates an IPA Inline Report section that specifies that nothing was inlined.

Predefined macros

None.