inline Specifier

The inline specifier instructs the compiler to replace function calls with the code of the function body. This substitution is “inline expansion” (sometimes called “inlining”). Inline expansion alleviates the function-call overhead at the potential cost of larger code size.

The inline keyword tells the compiler that inline expansion is preferred. However, the compiler can create a separate instance of the function (instantiate) and create standard calling linkages instead of inserting the code inline. Two cases where this can happen are:

• Recursive functions.
  
  
• Functions that are referred to through a pointer elsewhere in the translation unit.

Note that for a function to be considered as a candidate for inlining, it must use the new-style function definition. Functions that are declared as inline and that are not class member functions have internal linkage unless otherwise specified.

Microsoft Specific

The __inline keyword is equivalent to inline.

The __forceinline keyword instructs the compiler to inline the function without performing any cost/benefit analysis. The programmer must exercise good judgement in using this keyword. Indiscriminate use of __forceinline can result in larger, and sometimes even slower, code.

Even with __forceinline, the compiler cannot inline code in all circumstances. The compiler cannot inline a function if:

• The function or its caller is compiled with /Ob0 (the default option for debug builds).
  
  
• The function and the caller use different types of exception handling (C++ exception handling in one, structured exception handling in the other).
  
  
• The function has a variable argument list.
  
  
• The function uses inline assembly, unless compiled with /Og, /Ox, /O1, or /O2. 
  
  
• The function returns an unwindable object by value, when compiled with /GX, /EHs, or /EHa.
  
  
• The function receives a copy-constructed object passed by value, when compiled with /-GX, /EHs, or /EHa.
  
  
• The function is recursive and not accompanied by #pragma(inline_recursion, on). With the inline_recursion pragma, recursive functions can be inlined to a depth of eight calls, or as determined by the inline_depth pragma (see below).
  
  
• The function is virtual.
  
  
• The program takes the address of the function.

If the compiler cannot inline a function declared with __forceinline, it generates a level 1 warning (4714).

END Microsoft Specific

As with normal functions, there is no defined order of evaluation of the arguments to an inline function. In fact, it could be different from the order in which the arguments are evaluated when passed using normal function call protocol.

Microsoft Specific

Recursive functions can be substituted inline to a depth specified by the inline_depth pragma. After that depth, recursive function calls are treated as calls to an instance of the function. The inline_recursion pragma controls the inline expansion of a function currently under expansion. See the Inline-Function Expansion (/Ob) compiler option for related information.

END Microsoft Specific