/Ob (In-line Function Expansion)
Home | Overview | How Do I | Compiler Options
Feature Only in Professional and Enterprise Editions Code optimization is supported only in Visual C++ Professional and Enterprise Editions. For more information, see Visual C++ Editions.
The In-line Function Expansion (/Obn) options control inline expansion of functions, where n is one of the following:
Command Line Project Settings Description
/Ob0 Disable Disables inline expansion (default)
/Ob1 Only __inline Expands only functions marked as inline or __inline or, in a C++ member function, defined within a class declaration (default with /O1, /O2, and /Ox)
/Ob2 Any Suitable Expands functions marked as inline or __inline and any other function that the compiler chooses (expansion occurs at compiler discretion—often referred to as “auto-inlining”)
(To find this option in the development environment, click Settings on the Project menu. Then click the C/C++ tab, and click Optimizations in the Category box.)
The compiler treats the inline expansion options and keywords as suggestions. There is no guarantee that functions will be inlined. You cannot force the compiler to inline a particular function.
You can also use #pragma auto_inline to exclude functions from being considered as candidates for inline expansion. Also see #pragma intrinsic.
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 theinline_depth pragma. After that depth, recursive function calls are treated as calls to an instance of the function. Theinline_recursion pragma controls the inline expansion of a function currently under expansion. See theInline-Function Expansion (/Ob) compiler option for related information.
END Microsoft Specific
inline, __inline, __forceinline
inline
function_declarator; // C++ Specific
__inline
function_declarator;// Microsoft Specific
__forceinline
function_declarator;// Microsoft Specific
The inline and __inline keywords allow the compiler to insert a copy of the function body into each place the function is called. The insertion occurs only if the compiler's cost/benefit analysis show it to be profitable. The __forceinline keyword overrides the cost/benefit analysis and relies on the judgement of the programmer instead. Exercise caution when using __forceinline. Indiscriminate use of __forceinline can result in larger code with only marginal performance gains or, in some cases, even performance losses (due to increased paging of a larger executable, for example).
You cannot force the compiler to inline a function when conditions other than cost/benefit analysis prevent it. You 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 and is not compiled with /Og, /Ox, /O1, or /O2).
Function returns an unwindable object by value and is not 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 is not accompanied by #pragma(inline_recursion, on). With the pragma, recursive functions can be inlined to a default depth of eight calls. To change the inlining depth, use #pragma(inline_depth, n).
If the compiler cannot inline a function declared __forceinline, it generates a level 1 warning (4714).
The inline keyword is available only in C++. The __inline and __forceinline keywords are available in both C and C++. For compatibility with previous versions, _inline is a synonym for __inline.
Using inline functions can make your program faster because they eliminate the overhead associated with function calls. Functions expanded inline are subject to code optimizations not available to normal functions.
The /Ob compiler optimization option determines whether inline function expansion actually occurs.
For related information, see auto_inline.
Example 1
inline int max( int a , int b )
{
if( a > b ) return a;
return b;
}
A class's member functions can be declared inline either by using the inline keyword or by placing the function definition within the class definition.
Example 2
class MyClass
{
public:
void print() { cout << i << ''; } // Implicitly inline
private:
int i;
};
See Also Assembler (Inline) Topics