When Should I Write the Keyword 'Inline' For a Function/Method

When should I write the keyword 'inline' for a function/method?

Oh man, one of my pet peeves.

inline is more like static or extern than a directive telling the compiler to inline your functions. extern, static, inline are linkage directives, used almost exclusively by the linker, not the compiler.

It is said that inline hints to the compiler that you think the function should be inlined. That may have been true in 1998, but a decade later the compiler needs no such hints. Not to mention humans are usually wrong when it comes to optimizing code, so most compilers flat out ignore the 'hint'.

static - the variable/function name cannot be used in other translation units. Linker needs to make sure it doesn't accidentally use a statically defined variable/function from another translation unit.
extern - use this variable/function name in this translation unit but don't complain if it isn't defined. The linker will sort it out and make sure all the code that tried to use some extern symbol has its address.
inline - this function will be defined in multiple translation units, don't worry about it. The linker needs to make sure all translation units use a single instance of the variable/function.

Note: Generally, declaring templates inline is pointless, as they have the linkage semantics of inline already. However, explicit specialization and instantiation of templates require inline to be used.

Specific answers to your questions:

When should I write the keyword 'inline' for a function/method in C++?
Only when you want the function to be defined in a header. More exactly only when the function's definition can show up in multiple translation units. It's a good idea to define small (as in one liner) functions in the header file as it gives the compiler more information to work with while optimizing your code. It also increases compilation time.
When should I not write the keyword 'inline' for a function/method in C++?
Don't add inline just because you think your code will run faster if the compiler inlines it.
When will the compiler not know when to make a function/method 'inline'?
Generally, the compiler will be able to do this better than you. However, the compiler doesn't have the option to inline code if it doesn't have the function definition. In maximally optimized code usually all private methods are inlined whether you ask for it or not.
As an aside to prevent inlining in GCC, use __attribute__(( noinline )), and in Visual Studio, use __declspec(noinline).
Does it matter if an application is multithreaded when one writes 'inline' for a function/method?
Multithreading doesn't affect inlining in any way.

Is there still a use for inline? [duplicate]

I will try to explain my "secret understanding" the best way I can.

There are two entirely separate concepts here. One is the compiler's ability to replace a function call by repeating the function body directly at the call site. The other is the possibility of defining a function in more than one translation unit (= more than one .cpp file).

The first one is called function inlining. The second is the purpose of the inline keyword. Historically, the inline keyword was also a strong suggestion to the compiler that it should inline the function marked inline. As compilers became better at optimising, this functionality has receded, and using inline as a suggestion to inline a function is indeed obsolete. The compiler will happily ignore it and inline something else entirely if it finds that's a better optimisation.

I hope we've dealt with the explicit inline–inlining relationship. There is none in current code.

So, what is the actual purpose of the inline keyword? It's simple: a function marked inline can be defined in more than one translation unit without violating the One Definition Rule (ODR). Imagine these two files:

file1.cpp

int f() { return 42; }

int main()
{ return f(); }

file2.cpp

int f() { return 42; }

This command:

> gcc file1.cpp file2.cpp

Will produce a linker error, complaining that the symbol f is defined twice.

However, if you mark a function with the inline keyword, it specifically tells the compiler & linker: "You guys make sure that multiple identical definitions of this function do not result in any errors!"

So the following will work:

file1.cpp

inline int f() { return 42; }

int main()
{ return f(); }

file2.cpp

inline int f() { return 42; }

Compiling and linking these two files together will not produce any linker errors.

Notice that of course the definition of f doesn't have to be in the files verbatim. It can come from an #included header file instead:

f.hpp

inline int f() { return 42; }

file1.cpp

#include "f.hpp"

int main()
{ return f(); }

file2.cpp

#include "f.hpp"

Basically, to be able to write a function definition into a header file, you have to mark it as inline, otherwise it will lead to multiple definition errors.

The last piece of the puzzle is: why is the keyword actually spelled inline when it has nothing to do with inlining? The reason is simple: to inline a function (that is, to replace a call to it by repeating its body on the call site), the compiler must have the function's body in the first place.

C++ follows a separate compilation model, where the compiler doesn't have access to object files other than the one it's currently producing. Therefore, to be able to inline a function, its definition must be part of the current translation unit. If you want to be able to inline it in more than one translation unit, its definition has to be in all of them. Normally, this would lead to a multiple definition error. So if you put your function in a header and #include its definition everywhere to enable its inlining everywhere, you have to mark it as inline to prevent multiple definition errors.

Notice that even today, while a compiler will inline any function is sees fit, it must still have access to that function's definition. So while the inline keyword is not required as the hint "please inline this," you may still find you need to use it to enable the compiler to do the inlining if it chooses to do so. Without it, you might not be able to get the definition into the translation unit, and without the definition, the compiler simply cannot inline the function.

The compiler cannot. The linker can. Modern optimisation techniques include Link-Time Code Generation (a.k.a. Whole Program Optimisation), where the optimiser is run over all object files as part of the linking process, before the actual linking. In this step, all function definitions are of course available and inlining is perfectly possible without a single inline keyword being used anywhere in the program. But this optimisation is generally costly in build time, especially for large projects. With this in mind, relying solely on LTCG for inlining may not be the best option.

For completeness: I've cheated slightly in the first part. The ODR property is actually not a property of the inline keyword, but of inline functions (which is a term of the language). The rules for inline functions are:

Can be defined in multiple translation units without causing linker errors
Must be defined in every translation unit in which it is used
All its definitions must be token-for-token and entity-for-entity identical

The inline keyword turns a function into an inline function. Another way to mark a function as inline is to define (not just declare) it directly in a class definition. Such a function is inline automatically, even without the inline keyword.

When to use inline function and when not to use it?

Avoiding the cost of a function call is only half the story.

do:

use inline instead of #define
very small functions are good candidates for inline: faster code and smaller executables (more chances to stay in the code cache)
the function is small and called very often

don't:

large functions: leads to larger executables, which significantly impairs performance regardless of the faster execution that results from the calling overhead
inline functions that are I/O bound
the function is seldom used
constructors and destructors: even when empty, the compiler generates code for them
breaking binary compatibility when developing libraries:
- inline an existing function
- change an inline function or make an inline function non-inline: prior version of the library call the old implementation

when developing a library, in order to make a class extensible in the future you should:

add non-inline virtual destructor even if the body is empty
make all constructors non-inline
write non-inline implementations of the copy constructor and assignment operator unless the class cannot be copied by value

Remember that the inline keyword is a hint to the compiler: the compiler may decide not to inline a function and it can decide to inline functions that were not marked inline in the first place. I generally avoid marking function inline (apart maybe when writing very very small functions).

About performance, the wise approach is (as always) to profile the application, then eventually inline a set of functions representing a bottleneck.

References:

To Inline or Not To Inline
[9] Inline functions
Policies/Binary Compatibility Issues With C++
GotW #33: Inline
Inline Redux
Effective C++ - Item 33: Use inlining judiciously

EDIT: Bjarne Stroustrup, The C++ Programming Language:

A function can be defined to be inline. For example:

inline int fac(int n)
{
  return (n < 2) ? 1 : n * fac(n-1);
}

The inline specifier is a hint to the compiler that it should attempt to generate code for a call of fac() inline rather than laying down the code for the function once and then calling through the usual function call mechanism. A clever compiler can generate the constant 720 for a call fac(6). The possibility of mutually recursive inline functions, inline functions that recurse or not depending on input, etc., makes it impossible to guarantee that every call of an inline function is actually inlined. The degree of cleverness of a compiler cannot be legislated, so one compiler might generate 720, another 6 * fac(5), and yet another an un-inlined call fac(6).

To make inlining possible in the absence of unusually clever compilation and linking facilities, the definition–and not just the declaration–of an inline function must be in scope (§9.2). An inline especifier does not affect the semantics of a function. In particular, an inline function still has a unique address and so has static variables (§7.1.2) of an inline function.

EDIT2: ISO-IEC 14882-1998, 7.1.2 Function specifiers

A function declaration (8.3.5, 9.3, 11.4) 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.

Why use explicit inline when every class member function is implicitly inlined [duplicate]

If a definition of a member function is within the class body it is implicitly inline. If you only declare it in the class body and you place the definition outside of it you need to make it explicitly inline.

This can be done in two ways:

struct test {
   inline void foo();
};

void test::foo() {
}

struct test {
   void foo();
};

inline void test::foo() {
}

While both work, the second option is generally recommended.

C++ - What is the use of inline keyword if we should define method in header?

The historical reason for the inline keyword is that older C compilers weren't as capable of optimising code as good quality modern C and C++ compilers are. It was therefore, originally, introduced to allow the programmer to indicate a preference to inline a function (effectively insert the function body directly into the caller, which avoids overheads associated with function calls). Since there was no guarantee that a compiler could inline the function (e.g. some compilers could only inline certain types of functions) the inline keyword was made a hint rather than a directive.

The other typical use of inline is not as discretionary - if a function is defined in multiple compilation units (e.g. because the containing header is #included more than once) then leaving off inline causes a violation of the one definition rule (and therefore in undefined behaviour). inline is an instruction to the compiler (which in turn probably emits instructions to the linker) to resolve such incidental violations of the one-definition rule, and produce a working program (e.g. without causing the linker to complain about multiple definitions).

As to why it is still needed, functionally, the preprocessor only does text substitution ... such as replacing an #include directive with contents of the included header.

Let's consider two scenarios. The first has two source files (compilation units) that do;

 #include "some_header"

   //some other functions needed by the program, not pertinent here

and

 #include "some_header"

 int main()
 {
      foo();
 }

where some_header contains the definition

  void foo() { /* whatever */ }

The second scenario, however, omits the header file (yes, people do that) and has the first source file as

void foo() { /* whatever */ }

   //some other functions needed by the program, not pertinent here

and the second as;

 void foo() { /* whatever */ }

 int main()
 {
      foo();
 }

In both scenarios, assume the two compilation units are compiled and linked together. The result is a violation of the one definition rule (and, practically, typically results in a linker error due to multiply defined symbols).

Under current rules of the language (specifically, the preprocessor only doing text substitution), the two scenarios are required to be EXACTLY functionally equivalent. If one scenario was to print the value 42, the so should the other. If one has undefined behaviour (as is the case here) so does the other.

But, let's say for sake of discussion, that there was a requirement that a function be magically inlined if it is defined in a header. The code in the two scenarios would no longer be equivalent. The header file version would have defined behaviour (no violation of the one definition rule) and the second would have undefined behaviour.

Oops. We've just broken equivalence of the two scenarios. That may not seem much, but programmers would practically have trouble understanding why one version links and the other doesn't. And they would have have no way of fixing that ... other than moving code into a header file.

That means, we need some way to make the two scenarios equivalent. This means there needs to be something in the code which makes them equivalent. Enter the inline keyword, and prefix it to the definitions of foo().

Now, okay, one might argue that the preprocessor should do something a bit more intelligent i.e. do more than simple text substitution. But, now you are on a slippery slope. The C and C++ standards do (at length) specify that the preprocessor does that. And changing that would introduce a cascade of other changes. Whether that is a good idea or not (and, certainly, there is some advocacy for eliminating the preprocessor from C++ entirely), that is a much bigger change, with numerous ramifications on the language, and on programmers (who, whether it is good or bad, can rely on the preprocessor behaving as it does).

What is the use of the `inline` keyword in C?

Note: when I talk about .c files and .h files in this answer, I assume you have laid out your code correctly, i.e. .c files only include .h files. The distinction is that a .h file may be included in multiple translation units.

static inline void f(void) {} has no practical difference with static void f(void) {}.

In ISO C, this is correct. They are identical in behaviour (assuming you don't re-declare them differently in the same TU of course!) the only practical effect may be to cause the compiler to optimize differently.

inline void f(void) {} in C doesn't work as the C++ way. How does it work in C? What actually does extern inline void f(void); do?

This is explained by this answer and also this thread.

In ISO C and C++, you can freely use inline void f(void) {} in header files -- although for different reasons!

In ISO C, it does not provide an external definition at all. In ISO C++ it does provide an external definition; however C++ has an additional rule (which C doesn't), that if there are multiple external definitions of an inline function, then the compiler sorts it out and picks one of them.

extern inline void f(void); in a .c file in ISO C is meant to be paired with the use of inline void f(void) {} in header files. It causes the external definition of the function to be emitted in that translation unit. If you don't do this then there is no external definition, and so you may get a link error (it is unspecified whether any particular call of f links to the external definition or not).

In other words, in ISO C you can manually select where the external definition goes; or suppress external definition entirely by using static inline everywhere; but in ISO C++ the compiler chooses if and where an external definition would go.

In GNU C, things are different (more on this below).

To complicate things further, GNU C++ allows you to write static inline an extern inline in C++ code... I wouldn't like to guess on what that does exactly

I never really found a use of the inline keyword in my C programs, and when I see this keyword in other people's code, it's almost always static inline

Many coders don't know what they're doing and just put together something that appears to work. Another factor here is that the code you're looking at might have been written for GNU C, not ISO C.

In GNU C, plain inline behaves differently to ISO C. It actually emits an externally visible definition, so having a .h file with a plain inline function included from two translation units causes undefined behaviour.

So if the coder wants to supply the inline optimization hint in GNU C, then static inline is required. Since static inline works in both ISO C and GNU C, it's natural that people ended up settling for that and seeing that it appeared to work without giving errors.

, in which I see no difference with just static.

The difference is just in the intent to provide a speed-over-size optimization hint to the compiler. With modern compilers this is superfluous.

When to use 'inline' keyword in class methods with header and object files?

The inline keyword is important when you define a non-template function in a header file, but outside a class declaration. It avoids the multiple definition issue when a header is included in multiple places.

Other than that, it's not much use these days. It's technically still supposed to indicate that you want a function to use inline expansion -- i.e. instead of actually calling it (which presents a small overhead), the compiler just drops copies of the entire function body into whatever location it gets called from. (It's an invaluable optimisation for very small functions, such as accessor methods.) In reality though, compilers tend to figure out what should and shouldn't be inlined on their own, so it takes the keyword as little more than a hint.

When Should I Write the Keyword 'Inline' For a Function/Method