5.8.1.2 Inline Specifier

The inline function specifier is a recommendation that the compiler replace calls to the specified function with the function’s body, if possible. This can increase the execution speed of a program.

The rules for defining inline functions differ slightly to the C99 language standard in that a file scope declaration for a function using the inline function specifier (but not extern) is treated as an external definition of that function. This means that you do not need to provide an additional external definition of the function to build the code.

The following is an example of a function which has been made a candidate for in-lining.

inline int combine(int x, int y) {
  return 2 * x - y;
}

The compiler can either inline the function or call the function definition, at its discretion. Your code should not make any assumption about whether in-lining took place. A function containing in-line assembly will not be in-lined. Some generated assembly code sequences will also prevent in-lining of a function. A warning will be generated if the inline function references static objects (to comply with the C Standard) or is not in-lined successfully.

All function calls to a function that was in-lined by the compiler will be encoded as if the call was replaced with the body of the called function. This is performed at the assembly code level. in-lining will only take place if the assembly optimizers are enabled, which occurs at the higher optimization levels and which precludes this action if you are running an unlicensed compiler. The function itself might still be encoded normally by the compiler even if it is in-lined.

If in-lining takes place, this will increase the program’s execution speed, since the call/return sequences associated with the call will be eliminated. It will also reduce the hardware stack usage as no call instruction is executed; however, this stack-size reduction is not reflected in the call graphs, as these graphs are generated before in-lining takes place.

Code size can be reduced if the assembly code associated with the body of the in-lined function is very small, but code size can increase if the body of the in-lined function is larger than the call/return sequence it replaces. You should only consider this specifier for functions which generate small amounts of assembly code. Note that the amount of C code in the body of a function is not a good indicator of the size of the assembly code that it generates (see 3.5.13 How Can I Tell How Big a Function Is?).

This specifier performs the same task as the #pragma inline directive (see 5.14.3.3 The #pragma Inline Directive). Note that the optimizers can also implicitly inline small called-only-once routines (see 6.2 Assembly-Level Optimizations).

If the xc8-cc flag -Wpedantic is used, the inline keyword becomes unavailable, but you can use the __inline keyword.