View source for Inline function

{{short description|Function in the C and C++ programming languages}}
{{About|inline functions in C and C++|inline expansion more generally|Inline expansion}}
{{distinguish|Inline assembler}}
<noinclude>{{Requested move notice|1=Inline (C and C++)|2=Talk:Inline function#Requested move 27 May 2025}}
</noinclude>
{{Update|reason=Meaning of inline changed in C++ (https://en.cppreference.com/w/cpp/language/inline)|date=April 2019}}

In the [[C (programming language)|C]] and [[C++]] [[programming language]]s, an '''inline function''' is one qualified with the [[Keyword (computer programming)|keyword]] <code>inline</code>; this serves two purposes:
# It serves as a [[compiler directive]] that suggests (but does not require) that the [[compiler]] substitute the body of the function inline by performing [[inline expansion]], i.e. by inserting the function code at the address of each function call, thereby saving the overhead of a function call. In this respect it is analogous to the <code>register</code> [[storage class specifier]], which similarly provides an optimization hint.<ref name="meyers2002">{{cite journal |title=The New C: Inline Functions |url=http://www.drdobbs.com/the-new-c-inline-functions/184401540 |first=Randy |last=Meyers |date=July 1, 2002}}</ref>
# The second purpose of <code>inline</code> is to change linkage behavior; the details of this are complicated. This is necessary due to the C/C++ separate compilation + linkage model, specifically because the definition (body) of the function must be duplicated in all [[Translation unit (programming)|translation unit]]s where it is used, to allow inlining during ''compiling'', which, if the function has external [[Linkage (software)|linkage]], causes a collision during ''linking'' (it violates uniqueness of external symbols). C and C++ (and dialects such as GNU C and Visual C++) resolve this in different ways.<ref name="meyers2002"/>

== Example ==
An <code>inline</code> function can be written in C or C++ like this:
<syntaxhighlight lang="c">
inline void swap(int *m, int *n)
{
    int tmp = *m;
    *m = *n;
    *n = tmp;
}
</syntaxhighlight>
Then, a statement such as the following:
<syntaxhighlight lang="c">
swap(&x, &y);
</syntaxhighlight>
may be translated into (if the compiler decides to do the inlining, which typically requires optimization to be enabled):
<syntaxhighlight lang="c">
int tmp = x;
x = y;
y = tmp;
</syntaxhighlight>
When implementing a sorting algorithm doing lots of swaps, this can increase the execution speed.

== Standard support ==
[[C++]] and [[C99]], but not its predecessors [[K&R C]] and [[C89 (C version)|C89]], have support for <code>inline</code> functions, though with different semantics. In both cases, <code>inline</code> does not force inlining; the compiler is free to choose not to inline the function at all, or only in some cases. Different compilers vary in how complex a function they can manage to inline. Mainstream C++ compilers like [[Visual C Plus Plus|Microsoft Visual C++]] and [[GNU Compiler Collection|GCC]] support an option that lets the compilers automatically inline any suitable function, even those not marked as <code>inline</code> functions. However, simply omitting the <code>inline</code> keyword to let the compiler make all inlining decisions is not possible, since the linker will then complain about duplicate definitions in different translation units. This is because <code>inline</code> not only gives the compiler a hint that the function should be inlined, it also has an effect on whether the compiler will generate a callable out-of-line copy of the function (see [[#Storage classes of inline functions|storage classes of inline functions]]).

== Nonstandard extensions ==
[[GNU C]], as part of the dialect gnu89 that it offers, has support for <code>inline</code> as an extension to C89. However, the semantics differ from both those of C++ and C99. armcc in C90 mode also offers <code>inline</code> as a non-standard extension, with semantics different from gnu89 and C99.

Some implementations provide a means by which to force the compiler to inline a function, usually by means of implementation-specific declaration specifiers:
* Microsoft Visual C++: <code>__forceinline</code>
* gcc or clang: <code>__attribute__((always_inline))</code> or <code>__attribute__((__always_inline__))</code>, the latter of which is useful to avoid a conflict with a user-defined macro named <code>always_inline</code>.
Indiscriminate uses of that can result in larger code (bloated executable file), minimal or no performance gain, and in some cases even a loss in performance. Moreover, the compiler cannot inline the function in all circumstances, even when inlining is forced; in this case both gcc and Visual C++ generate warnings.

Forcing inlining is useful if:
* <code>inline</code> is not respected by the compiler (ignored by compiler cost/benefit analyzer)
* inlining results is necessary for boosting performance

For code portability, the following preprocessor directives may be used:
<syntaxhighlight lang="cpp">
#ifdef _MSC_VER
    #define forceinline __forceinline
#elif defined(__GNUC__)
    #define forceinline inline __attribute__((__always_inline__))
#elif defined(__CLANG__)
    #if __has_attribute(__always_inline__)
        #define forceinline inline __attribute__((__always_inline__))
    #else
        #define forceinline inline
    #endif
#else
    #define forceinline inline
#endif
</syntaxhighlight>

== Storage classes of inline functions ==
<code>static inline</code> has the same effects in all C dialects and C++. It will emit a locally visible (out-of-line copy of the) function if required.

Regardless of the storage class, the compiler can ignore the <code>inline</code> qualifier and generate a function call in all C dialects and C++.

The effect of the storage class <code>extern</code> when applied or not applied to <code>inline</code> functions differs between the C dialects<ref name="inline-c99-vs-gnu">{{Cite web|url=http://www.greenend.org.uk/rjk/tech/inline.html|title = Inline Functions in C}}</ref> and C++.<ref name="gcc-inline">{{Cite web|url=https://gcc.gnu.org/onlinedocs/gcc-7.1.0/gcc/Inline.html|title = Using the GNU Compiler Collection (GCC): Inline}}</ref>

=== C99 ===
In C99, a function defined <code>inline</code> will never, and a function defined <code>extern inline</code> will always, emit an externally visible function. Unlike in C++, there is no way to ask for an externally visible function shared among translation units to be emitted only if required.

If <code>inline</code> declarations are mixed with <code>extern inline</code> declarations or with unqualified declarations (ie., without <code>inline</code> qualifier or storage class), the translation unit must contain a definition (no matter whether unqualified, <code>inline</code>, or <code>extern inline</code>) and an externally visible function will be emitted for it.

A function defined <code>inline</code> requires exactly one function with that name somewhere else in the program which is either defined <code>extern inline</code> or without qualifier. If more than one such definition is provided in the whole program, the linker will complain about duplicate symbols. If, however, it is lacking, the linker does not necessarily complain, because, if all uses could be inlined, it is not needed. But it may complain, since the compiler can always ignore the <code>inline</code> qualifier and generate calls to the function instead, as typically happens if the code is compiled without optimization. (This may be the desired behavior, if the function is supposed to be inlined everywhere by all means, and an error should be generated if it is not.)  A convenient way is to define the <code>inline</code> functions in header files and create one .c file per function, containing an <code>extern inline</code> declaration for it and including the respective header file with the definition. It does not matter whether the declaration is before or after the include.

To prevent [[unreachable code]] from being added to the final executable if all uses of a function were inlined, it is advised<ref name="gcc-inline"/> to put the object files of all such .c files with a single <code>extern inline</code> function into a [[static library]] file, typically with <code>ar rcs</code>, then link against that library instead of the individual object files. That causes only those object files to be linked that are actually needed, in contrast to linking the object files directly, which causes them to be always included in the executable. However, the library file must be specified after all the other object files on the linker command line, since calls from object files specified after the library file to the functions will not be considered by the linker. Calls from <code>inline</code> functions to other <code>inline</code> functions will be resolved by the linker automatically (the <code>s</code> option in <code>ar rcs</code> ensures this).

An alternative solution is to use link time optimization instead of a library. gcc provides the flag <code>-Wl,--gc-sections</code> to omit sections in which all functions are unused. This will be the case for object files containing the code of a single unused <code>extern inline</code> function. However, it also removes any and all other unused sections from all other object files, not just those related to unused <code>extern inline</code> functions. (It may be desired to link functions into the executable that are to be called by the programmer from the debugger rather than by the program itself, eg., for examining the internal state of the program.) With this approach, it is also possible to use a single .c file with all <code>extern inline</code> functions instead of one .c file per function. Then the file has to be compiled with <code>-fdata-sections -ffunction-sections</code>. However, the gcc manual page warns about that, saying "Only use these options when there are significant benefits from doing so."

Some recommend an entirely different approach, which is to define functions as <code>static inline</code> instead of <code>inline</code> in header files.<ref name="inline-c99-vs-gnu"/> Then, no unreachable code will be generated. However, this approach has a drawback in the opposite case: Duplicate code will be generated if the function could not be inlined in more than one translation unit. The emitted function code cannot be shared among translation units because it must have different addresses. This is another drawback; taking the address of such a function defined as <code>static inline</code> in a header file will yield different values in different translation units. Therefore, <code>static inline</code> functions should only be used if they are used in only one translation unit, which means that they should only go to the respective .c file, not to a header file.

=== gnu89 ===
gnu89 semantics of <code>inline</code> and <code>extern inline</code> are essentially the exact opposite of those in C99,<ref>{{Cite web|url=http://blahg.josefsipek.net/?p=529|title = Josef "Jeff" Sipek » GNU inline vs. C99 inline}}</ref> with the exception that gnu89 permits redefinition of an <code>extern inline</code> function as an unqualified function, while C99 <code>inline</code> does not.<ref name="gcc-5-porting">{{Cite web|url=https://gcc.gnu.org/gcc-5/porting_to.html|title = Porting to GCC 5 - GNU Project}}</ref> Thus, gnu89 <code>extern inline</code> without redefinition is like C99 <code>inline</code>, and gnu89 <code>inline</code> is like C99 <code>extern inline</code>; in other words, in gnu89, a function defined <code>inline</code> will always and a function defined <code>extern inline</code> will never emit an externally visible function. The rationale for this is that it matches variables, for which storage will never be reserved if defined as <code>extern</code> and always if defined without. The rationale for C99, in contrast, is that it would be [[principle of least astonishment|astonishing]] if using <code>inline</code> would have a side-effect&mdash;to always emit a non-inlined version of the function&mdash;that is contrary to what its name suggests.

The remarks for C99 about the need to provide exactly one externally visible function instance for inlined functions and about the resulting problem with unreachable code apply mutatis mutandis to gnu89 as well.

gcc up to and including version 4.2 used gnu89 <code>inline</code> semantics even when <code>-std=c99</code> was explicitly specified.<ref>{{Cite web|url=https://gcc.gnu.org/ml/gcc-patches/2007-02/msg00119.html|title = Ian Lance Taylor - Clean up extern inline}}</ref> With version 5,<ref name="gcc-5-porting"/> gcc switched from gnu89 to the gnu11 dialect, effectively enabling C99 <code>inline</code> semantics by default. To use gnu89 semantics instead, they have to be enabled explicitly, either with <code>-std=gnu89</code> or, to only affect inlining, <code>-fgnu89-inline</code>, or by adding the <code>gnu_inline</code> attribute to all <code>inline</code> declarations. To ensure C99 semantics, either <code>-std=c99</code>, <code>-std=c11</code>, <code>-std=gnu99</code> or <code>-std=gnu11</code> (without <code>-fgnu89-inline</code>) can be used.<ref name="gcc-inline"/>

=== C++ ===
In C++, a function defined <code>inline</code> will, if required, emit a function shared among translation units, typically by putting it into the common section of the object file for which it is needed. The function must have the same definition everywhere, always with the <code>inline</code> qualifier. In C++, <code>extern inline</code> is the same as <code>inline</code>. The rationale for the C++ approach is that it is the most convenient way for the programmer, since no special precautions for elimination of unreachable code must be taken and, like for ordinary functions, it makes no difference whether <code>extern</code> is specified or not.

The <code>inline</code> qualifier is automatically added to a function defined as part of a class definition.

=== armcc ===
armcc in C90 mode provides <code>extern inline</code> and <code>inline</code> semantics that are the same as in C++: Such definitions will emit a function shared among translation units if required. In C99 mode, <code>extern inline</code> always emits a function, but like in C++, it will be shared among translation units. Thus, the same function can be defined <code>extern inline</code> in different translation units.<ref>{{Cite web|url=http://infocenter.arm.com/help/topic/com.arm.doc.faqs/ka15831.html|title=Documentation – Arm Developer}}</ref> This matches the traditional behavior of Unix C compilers<ref>gcc manual page, description of <code>-fno-common</code></ref> for multiple non-<code>extern</code> definitions of uninitialized global variables.

== Restrictions ==
Taking the address of an <code>inline</code> function requires code for a non-inlined copy of that function to be emitted in any case.

In C99, an <code>inline</code> or <code>extern inline</code> function must not access <code>static</code> global variables or define non-<code>const</code> <code>static</code> local variables. <code>const static</code> local variables may or may not be different objects in different translation units, depending on whether the function was inlined or whether a call was made. Only <code>static inline</code> definitions can reference identifiers with internal linkage without restrictions; those will be different objects in each translation unit. In C++, both <code>const</code> and non-<code>const</code> <code>static</code> locals are allowed and they refer to the same object in all translation units.

gcc cannot inline functions if<ref name="gcc-inline"/>
# they are [[variadic function|variadic]],
# use <code>[[alloca]]</code>
# use computed <code>goto</code>
# use nonlocal <code>goto</code>
# use [[nested function]]s
# use <code>setjmp</code>
# use <code>__builtin_longjmp</code>
# use <code>__builtin_return</code>, or
# use <code>__builtin_apply_args</code>

Based on Microsoft Specifications at MSDN, MS Visual C++ cannot inline (not even with <code>__forceinline</code>), 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 is [[Recursion (computer science)|recursive]] and not accompanied by <code>#pragma inline_recursion(on)</code>. With the pragma, recursive functions are inlined to a default depth of 16 calls. To reduce the inlining depth, use <code>inline_depth</code> pragma.
# The function is [[virtual function|virtual]] and is called virtually. Direct calls to virtual functions can be inlined.
# The program takes the address of the function and the call is made via the pointer to the function. Direct calls to functions that have had their address taken can be inlined.
# The function is also marked with the naked <code>__declspec</code> modifier.

==Problems==
{{see also|Inline expansion#Effect on performance}}

Besides the problems with inline expansion in general (see {{Section link|Inline expansion#Effect on performance}}), <code>inline</code> functions as a language feature may not be as valuable as they appear, for a number of reasons:
* Often, a compiler is in a better position than a human to decide whether a particular function should be inlined. Sometimes the compiler may not be able to inline as many functions as the programmer indicates.
* An important point to note is that the code (of the <code>inline</code> function) gets exposed to its client (the calling function).
* As functions evolve, they may become suitable for inlining where they were not before, or no longer suitable for inlining where they were before. While inlining or un-inlining a function is easier than converting to and from macros, it still requires extra maintenance which typically yields relatively little benefit.
* Inline functions used in proliferation in native C-based compilation systems can increase compilation time, since the intermediate representation of their bodies is copied into each call site.
* The specification of <code>inline</code> in C99 requires exactly one external definition of the function, if it is used somewhere. If such a definition wasn't provided by the programmer, that can easily lead to linker errors. This can happen with optimization turned off, which typically prevents inlining. Adding the definitions, on the other hand, can cause unreachable code if the programmer does not carefully avoid it, by putting them in a library for linking, using link time optimization, or <code>static inline</code>.
* In C++, it is necessary to define an <code>inline</code> function in every module (translation unit) that uses it, whereas an ordinary function must be defined in only a single module.  Otherwise it would not be possible to compile a single module independently of all other modules.  Depending on the compiler, this may cause each respective object file to contain a copy of the function's code, for each module with some use that could not be inlined.
* In [[embedded software]], oftentimes certain functions need to be placed in certain code sections by use of special compiler instructions such as "pragma" statements.  Sometimes, a function in one memory segment might need to call a function in another memory segment, and if inlining of the called function occurs, then the code of the called function might end up in a segment where it shouldn't be.  For example, high-performance memory segments may be very limited in code space, and if a function belonging in such a space calls another large function that is not meant to be in the high-performance section and the called function gets inappropriately inlined, then this might cause the high-performance memory segment to run out of code space.  For this reason, sometimes it is necessary to ensure that functions do ''not'' become inlined.

== Quotes ==
{{blockquote
 |text=A function declaration{{nbsp}}... with an '''inline''' specifier declares an inline function. The '''inline''' specifier indicates to the implementation that inline substitution of the function body at the point of call is to be preferred to the usual function call mechanism. An implementation is not required to perform this inline substitution at the point of call; however, even if this inline substitution is omitted, the other rules for inline functions defined by 7.1.2 shall still be respected.
 |author=ISO/IEC 14882:2011, the current C++ standard, section 7.1.2
}}

{{blockquote
 |text=A function declared with an '''inline''' function specifier is an inline function{{nbsp}}... Making a function an inline function suggests that calls to the function be as fast as possible. The extent to which such suggestions are effective is implementation-defined (''footnote: For example, an implementation might never perform inline substitution, or might only perform inline substitutions to calls in the scope of an inline declaration.'')
...{{nbsp}}An inline definition does not provide an external definition for the function, and does not forbid an external definition in another [[Translation unit (programming)|translation unit]]. An inline definition provides an alternative to an external definition, which a translator may use to implement any call to the function in the same translation unit. It is unspecified whether a call to the function uses the inline definition or the external definition.
 |multiline=yes
 |author=ISO 9899:1999(E), the C99 standard, section 6.7.4
}}

== See also ==
* [[Macro (computer science)]]

== References ==
{{reflist}}
{{refbegin}}
*{{cite book|last=JANA|first=DEBASISH|title=C++ AND OBJECT-ORIENTED PROGRAMMING PARADIGM|url=https://books.google.com/books?id=DnsM0WD-6iMC&pg=PA131|date=1 January 2005|publisher=PHI Learning Pvt. Ltd.|isbn=978-81-203-2871-6}}
*{{cite book|last=Sengupta|first=Probal|title=Object-Oriented Programming: Fundamentals And Applications|url=https://books.google.com/books?id=ZLzt5WtsdzIC&pg=PA50|date=1 August 2004|publisher=PHI Learning Pvt. Ltd.|isbn=978-81-203-1258-6}}
*{{cite book|last=Svenk|first=Goran|title=Object-oriented Programming: Using C++ for Engineering and Technology|url=https://books.google.com/books?id=Miq73i_J1i4C&pg=PA36|year=2003|publisher=Cengage Learning|isbn=0-7668-3894-3}}
*{{cite book|author=Balagurusamy|title=Object Oriented Programming with C++|url=https://books.google.com/books?id=WCHZAgAAQBAJ&pg=PA74|year=2013|publisher=Tata McGraw-Hill Education|isbn=978-1-259-02993-6}}
*{{cite book|last1=Kirch-Prinz|first1=Ulla|last2=Prinz|first2=Peter|title=A Complete Guide to Programming in C++|url=https://books.google.com/books?id=-yhuY0Wg_QcC&pg=PA181|year=2002|publisher=Jones & Bartlett Learning|isbn=978-0-7637-1817-6}}
*{{cite book|last=Conger|first=David|title=Creating Games in C++: A Step-by-step Guide|url=https://books.google.com/books?id=1F6ipojt7DcC&pg=PA79|year=2006|publisher=New Riders|isbn=978-0-7357-1434-2}}
*{{cite book|last=Skinner|first=M. T.|title=The Advanced C++ Book|url=https://books.google.com/books?id=fgGLZ7WYxCMC&pg=PA97|year=1992|publisher=Silicon Press|isbn=978-0-929306-10-0}}
*{{cite book|author=Love|title=Linux Kernel Development|url=https://books.google.com/books?id=NXVkcCjPblcC&pg=PA18|date=1 September 2005|publisher=Pearson Education|isbn=978-81-7758-910-8}}
*{{cite book|last1=DEHURI|first1=SATCHIDANANDA|last2=JAGADEV|first2=ALOK KUMAR|last3=RATH|first3=AMIYA KUMAR|title=OBJECT-ORIENTED PROGRAMMING USING C++|url=https://books.google.com/books?id=fxUVrhjD4k0C&pg=PA78|date=8 May 2007|publisher=PHI Learning Pvt. Ltd.|isbn=978-81-203-3085-6}}
{{refend}}

== External links ==
* [https://gcc.gnu.org/onlinedocs/gcc/Inline.html Inline functions] with the [[GNU Compiler Collection]] (GCC)
* [https://lists.llvm.org/pipermail/llvm-dev/2021-August/152031.html Summary of "inline" semantics in C and C++], by [[LLVM]] contributor David Chisnall

{{DEFAULTSORT:Inline Function}}
[[Category:Software optimization]]