Let's say that I have a library which contains a public definition of function void foo();. The library calls this function internally. To get the best performance I want internal calls to be inlined. I also want to prevent external code from seeing the definition so that later I can change the implementation without breaking the ABI. Here is a piece of code:
MyLib.h:
void foo();
MyLibInlined.h:
inline void foo() { code here }
MyLib.cpp
#define inline
#include "MyLibInlined.h"
The question is does it break the ODR or is it considered bad practice?
EDIT:
What if foo was a member function?
The question is does it break the ODR or is it considered bad practice?
It doesn't break the ODR, but it breaks the rules in [dcl.fct.spec]:
If a function with external linkage is
declared inline in one translation unit, it shall be declared inline in all translation units in which it appears;
no diagnostic is required.
Instead you should have a public version of the function, which is not declared inline, and have an internal version which you use inside your library:
// MyLibInlined.h
inline void foo_impl() { }
Then inside the library define foo as a call to the internal one:
// MyLib.cpp
#include "MyLibInlined.h"
void foo() { foo_impl(); }
Alternatively, if all the calls to foo() are in a single file you don't need to worry at all, just define it as a non-inline function, and let the compiler inline it in the file where the definition is visible:
// MyLib.h
void foo();
// MyLib.cpp
void foo() { code here }
// use foo ...
The inline keyword doesn't mean the function will be inlined, it means the definition is provided inline in headers. The compiler doesn't need that keyword to be able to inline it within the file where it's defined, because it can see the definition. You only need the inline keyword to allow the definition to appear in multiple translation units without causing a multiple definition error.
AFAIK it does break the ODR, since inline is not so much a rule as it is a guideline. The compiler is allowed to not inline functions despite them being declared so.
On the other hand compilers are also allowed to inline functions that are not declared inline, and are likely to do so for small functions in internal calls (it can do so at link-time in some cases), so just don't worry about it.
Alternatively declare the inline version in a separate namespace and use inline namespaces to resolve it at compile-time (or using or whatever)(http://en.cppreference.com/w/cpp/language/namespace#Inline_namespaces)
It seems to be illegal based on this (C++14 3.2/6)
There can be more than one definition of a [...] inline function with
external linkage [...] in a program provided that each definition
appears in a different translation unit, and provided the definitions satisfy the following requirements. Given
such an entity named D defined in more than one translation unit, then
[...]
— each definition of D shall consist of the same sequence of tokens
Section 3.2 is the section on the one definition rule.
This might be a cleaner variation on what you're doing:
// foo_pub.h -- public interface
#define foo() foo_pub()
void foo_pub();
// foo_private.h -- internal used by library
#define foo() foo_inline()
inline foo_inline() { ... }
// foo_pub.c -- definition for public function
void
foo_pub()
{
foo_inline()
}
Related
There is a rule in the standard (N4659, dcl.inline/6):
If a function or variable with external linkage is declared inline in one translation
unit, it shall be declared inline in all translation units in which it appears; no diagnostic is required.
(there is a similar rule in the current draft standard as well)
Why does this rule use the word "appears"? Instead of "appears", I would have expected that the function/variable need to be odr-used, or some other stronger requirement than "appears". What kind of problems can it cause if an inline function just appears (but otherwise unused) as non-inline in a translation unit?
Note: this issue comes up if one wants to put inline functions into their own separate header to speed up compilation (there are cases when only the class definition is needed, inline function are not). And to make it easy to change inline-ness, class definition only contains member function declarations which are not marked inline, and then functions are marked inline at function definition. For example, if I'd like to change a non-inline function to inline, all I need is to move the function from the cpp to the header file and add inline to the function definition (no need to edit member function declaration in the class definition - it's one extra place to edit). But the mentioned rule makes this approach invalid.
A concrete example:
Contents of Foo_def.hpp:
struct Foo {
void bar(); // note: no inline specifier
};
Contents of Foo_inl.hpp:
#include "Foo_def.hpp"
inline void Foo::bar() { // note: inline is specified here
// do something useful
}
Contents of a.cpp:
#include "Foo_def.hpp"
#include "Foo_inl.hpp"
void callBar() {
Foo f;
f.bar();
}
Contents of b.cpp:
#include "Foo_def.hpp" // note, Foo_inl.hpp is not included
int sizeOfFoo() {
return sizeof(Foo);
}
If both a.cpp and b.cpp is linked in a program, then it is ill-formed according to the cited rule, because Foo::bar is an inline function, yet it is not declared as such in b.cpp. But this is odd, because Foo::bar is not used at all in b.cpp, so whether Foo::bar is inline or not shouldn't matter.
The trivial answer is that the function might never get emitted for a translation unit that needs it:
int f();
int g();
int main() {return f()+g();}
inline int f() {return 1;}
int g() {return 0;}
The second translation unit has no reason to generate code for the unused inline function (it would be unfortunate for it to do so if there were many such functions brought in by headers), but the first one can’t.
Allowing definitions that differed (only) in whether they were inline could address this, but would require the linker to deal with strong and weak symbols with the same name unless (like C) you were required to provide both kinds if the address of the function were ever taken.
NB This is not a question about how to use inline functions or how they work, more why they are done the way they are.
The declaration of a class member function does not need to define a function as inline, it is only the actual implementation of the function. For example, in the header file:
struct foo{
void bar(); // no need to define this as inline
}
So why does the inline implementation of a classes function have to be in the header file? Why can't I put the inline function the .cpp file? If I were to try to put the inline definition in the .cpp file I would get an error along the lines of:
error LNK2019: unresolved external symbol
"public: void __thiscall foo::bar(void)"
(?bar#foo##QAEXXZ) referenced in function _main
1>C:\Users\Me\Documents\Visual Studio 2012\Projects\inline\Debug\inline.exe
: fatal error LNK1120: 1 unresolved externals
The definition of an inline function doesn't have to be in a header file but, because of the one definition rule (ODR) for inline functions, an identical definition for the function must exist in every translation unit that uses it.
The easiest way to achieve this is by putting the definition in a header file.
If you want to put the definition of a function in a single source file then you shouldn't declare it inline. A function not declared inline does not mean that the compiler cannot inline the function.
Whether you should declare a function inline or not is usually a choice that you should make based on which version of the one definition rules it makes most sense for you to follow; adding inline and then being restricted by the subsequent constraints makes little sense.
There are two ways to look at it:
Inline functions are defined in the header because, in order to inline a function call, the compiler must be able to see the function body. For a naive compiler to do that, the function body must be in the same translation unit as the call. (A modern compiler can optimize across translation units, and so a function call may be inlined even though the function definition is in a separate translation unit, but these optimizations are expensive, aren't always enabled, and weren't always supported by the compiler)
functions defined in the header must be marked inline because otherwise, every translation unit which includes the header will contain a definition of the function, and the linker will complain about multiple definitions (a violation of the One Definition Rule). The inline keyword suppresses this, allowing multiple translation units to contain (identical) definitions.
The two explanations really boil down to the fact that the inline keyword doesn't exactly do what you'd expect.
A C++ compiler is free to apply the inlining optimization (replace a function call with the body of the called function, saving the call overhead) any time it likes, as long as it doesn't alter the observable behavior of the program.
The inline keyword makes it easier for the compiler to apply this optimization, by allowing the function definition to be visible in multiple translation units, but using the keyword doesn't mean the compiler has to inline the function, and not using the keyword doesn't forbid the compiler from inlining the function.
This is a limit of the C++ compiler. If you put the function in the header, all the cpp files where it can be inlined can see the "source" of your function and the inlining can be done by the compiler. Otherwhise the inlining would have to be done by the linker (each cpp file is compiled in an obj file separately). The problem is that it would be much more difficult to do it in the linker. A similar problem exists with "template" classes/functions. They need to be instantiated by the compiler, because the linker would have problem instantiating (creating a specialized version of) them. Some newer compiler/linker can do a "two pass" compilation/linking where the compiler does a first pass, then the linker does its work and call the compiler to resolve unresolved things (inline/templates...)
The c++ inline keyword is misleading, it doesn't mean "inline this function". If a function is defined as inline, it simply means that it can be defined multiple times as long as all definitions are equal. It's perfectly legal for a function marked inline to be a real function that is called instead of getting code inlined at the point where it's called.
Defining a function in a header file is needed for templates, since e.g. a templated class isn't really a class, it's a template for a class which you can make multiple variations of. In order for the compiler to be able to e.g. make a Foo<int>::bar() function when you use the Foo template to create a Foo class, the actual definition of Foo<T>::bar() must be visible.
The reason is that the compiler has to actually see the definition in order to be able to drop it in in place of the call.
Remember that C and C++ use a very simplistic compilation model, where the compiler always only sees one translation unit at a time. (This fails for export, which is the main reason only one vendor actually implemented it.)
I know this is an old thread but thought I should mention that the extern keyword. I've recently ran into this issue and solved as follows
Helper.h
namespace DX
{
extern inline void ThrowIfFailed(HRESULT hr);
}
Helper.cpp
namespace DX
{
inline void ThrowIfFailed(HRESULT hr)
{
if (FAILED(hr))
{
std::stringstream ss;
ss << "#" << hr;
throw std::exception(ss.str().c_str());
}
}
}
Because the compiler needs to see them in order to inline them. And headers files are the "components" which are commonly included in other translation units.
#include "file.h"
// Ok, now me (the compiler) can see the definition of that inline function.
// So I'm able to replace calls for the actual implementation.
Inline Functions
In C++ a macro is nothing but inline function. SO now macros are under control of compiler.
Important : If we define a function inside class it will become Inline automatically
Code of Inline function is replaced at the place it is called, so it reduce the overhead of calling function.
In some cases Inlining of function can not work, Such as
If static variable used inside inline function.
If function is complicated.
If recursive call of function
If address of function taken implicitely or explicitely
Function defined outside class as below may become inline
inline int AddTwoVar(int x,int y); //This may not become inline
inline int AddTwoVar(int x,int y) { return x + y; } // This becomes inline
Function defined inside class also become inline
// Inline SpeedMeter functions
class SpeedMeter
{
int speed;
public:
int getSpeed() const { return speed; }
void setSpeed(int varSpeed) { speed = varSpeed; }
};
int main()
{
SpeedMeter objSM;
objSM.setSpeed(80);
int speedValue = A.getSpeed();
}
Here both getSpeed and setSpeed functions will become inline
I'm trying to extern an inline function. How I thought it should work:
//a.cpp
inline void f(int) {}
//b.cpp
extern void f(int);
int main() { f(4); }
But getting link error. Then by reading this ("1) It must be declared inline in every translation unit."). What I've tried:
//a.cpp
inline void f(int) {}
//b.cpp
extern inline void f(int);
int main() { f(4); }
Still getting link error. But now, trying something that I don't know what I'm doing:
//a.cpp
extern inline void f(int) {}
//b.cpp
extern inline void f(int);
int main() { f(4); }
It works. What's happening here? Before adding extern to everything, f in a.cpp had internal linkage?
I'm using MSVC 2017 (v141) with /permissive- and /std:c++17
I'm trying to extern an inline function.
There is no reason to use extern with a function. See storage duration - linkage. Functions have external linkage by default; in order to not have external linkage, something special needs to be done (i.e. put it in an anonymous namespace or declare it static). So the normal use of an inline function already exhibits external linkage with no need for the extern keyword.
How I thought it should work:
//a.cpp
inline void f(int) {}
//b.cpp
extern void f(int);
int main() { f(4); }
Then by reading this ("1) It must be declared inline in every translation unit.").
That reference is correct, but look up a bit more where it says "The definition of an inline function [...] must be present in the translation unit where it is accessed [...]." Your example has a declaration of f in b.cpp, but not a definition. If you are going to call f from b.cpp, you need the full definition in that translation unit, as in:
inline void f(int) {}
(This is the same code that exists in a.cpp.) If you leave off the curly braces, then you have a declaration but not a definition, making it illegal to call f from that translation unit.
Basically, it is a real pain to define an inline function outside a header file, unless you give it internal linkage. That's because each source file that uses the inline function would need its own copy of the function body, meaning that if you change the function, you need to make that change in multiple files. Oof. Don't do it. Define each of your inline functions in a header file. If you think you want to define one in a source file, you probably misunderstand what "inline" means.
What does "inline" mean?
As far as the compiler is concerned, the inline keyword means (almost) nothing. It is just a flag on a function definition that gets propagated into the object code so that the linker sees it. The compiler processes the function just as it would any other function. The function may be called normally, or calls to it might be inlined – just like any other function.
The one case where the compiler might do something with the inline flag is when a function is declared inline, is used, but lacks a definition. This is an error that can be caught before the linker takes over. It does not have to be caught by the compiler, but it can be. (If not caught by the compiler, it would be caught by the linker.)
Moving on to the linking stage. When the linker sees the inline flag, it suspends the one-definition rule for that function. The linker will expect to see a definition of the function in each translation unit that still uses the function after the compiler's optimizations. It gets to choose any one of those definitions to serve as the final implementation. Hence the reason that all definitions must match.
And that's about it. The inline keyword basically means that the function definition is in a header file. It tells the linker to not complain when that definition appears in multiple translation units, because that is expected.
Going back to the question, it looks like the intent was to declare an inline function whose definition would appear in only one translation unit. In other words, the function would be flagged as defined in multiple translation units, but the definition would be in only one. Kind of inconsistent there, if not outright contradictory.
I was wondering if there is an easy way to use definitions as inline inside a shared library, but still export symbols for other application to import.
According to the letter of the standard this is not possible.
[dcl.inline]
6. An inline function or variable shall be defined in every translation unit in which it is odr-used and shall have exactly the same definition in every case [...] If a function or variable with external linkage is declared inline in one translation
unit, it shall be declared inline in all translation units in which it appears; no diagnostic is required.
So the same function cannot be inline in a part of a program and non-inline in another part. You have to use a wrapper.
gcc has a way to export inline functions. Try -fkeep-inline-functions or __attribute__((used)). It isn't clear how useful this is in the context of C++, as according to the rules you have to export inline function definitions for all to see, and then they will be inlined by the client of your shared library. Clang only supports __attribute__((used)).
If you are willing to play lose with the standard, you can try to ignore either of the two quoted sentences and hope for the best. I have tried both methods with gcc and they both appear to work, however they both result in undefined behaviour, so no guarantees.
An inline function or variable shall be defined in every translation unit in which it is odr-used --- ignore this. Just don't define it when you are not compiling the library. Mark it with __attribute__((used)) so that the symbol is emitted.
class X {
inline void foo();
};
#ifdef BUILDING_SHARED_LIB
void __attribute__((used)) X::foo() {}
#endif
it shall be declared inline in all translation units in which it appears --- ignore this. Just don''t declare it inline (and of course don't define it) when you are not compiling the library. Mark it with __attribute__((used)) so that the symbol is emitted.
class X {
void foo();
};
#ifdef BUILDING_SHARED_LIB
inline void __attribute__((used)) X::foo() {}
#endif
Both methods appear to work for me, however as I've said no guarantees can be given as this is UB according to the standard. The Itanium ABI however doesn't care if a function is declared inline or not, so one can possibly regard the ABI as giving the guarantee in case 2. I cannot vouch for this.
You can use a wrapper for export:
// public header
MY_DLL_INTERFACE void foo(void);
// private header
inline void foo_impl(void) { … }
// impl
void foo(void) { foo_impl(); }
I have a class that had an inline member, but I later decided that I wanted to remove the implementation from the headers so I moved the members body of the functions out to a cpp file. At first I just left the inlined signature in the header file (sloppy me) and the program failed to link correctly. Then I fixed my header and it all works fine, of course.
But wasn't inline totally optional?
In code:
First:
//Class.h
class MyClass
{
void inline foo()
{}
};
Next changed to (won't link):
//Class.h
class MyClass
{
void inline foo();
};
//Class.cpp
void MyClass::foo()
{}
And then to (will work fine):
//Class.h
class MyClass
{
void foo();
};
//Class.cpp
void MyClass::foo()
{}
I thought inline was optional, and imagined I might get by with a warning for my sloppiness, but didn't expect a linking error. What's the correct/standard thing a compiler should do in this case, did I deserve my error according to the standard?
Indeed, there is this one definition rule saying that an inline function must be defined in every translation unit it is used. Gory details follow. First 3.2/3:
Every program shall contain exactly one definition of every non-inline function or object that is used in that program; no diagnostic required. The definition can appear explicitly in the program, it can be found in the standard or a user-defined library, or (when appropriate) it is implicitly defined (see 12.1, 12.4 and 12.8).
An inline function shall be defined in every translation unit in which it is used.
And of course 7.1.2/4:
An inline function shall be defined in every translation unit in which it is used and shall have exactly the same definition in every case (3.2). [Note: a call to the inline function may be encountered before its definition appears in the translation unit. ] If a function with external linkage is declared inline in one translation unit, it shall be declared inline in all translation units in which it appears; no diagnostic is required. An inline function with external linkage shall have the same address in all translation units. A static local variable in an extern inline function always refers to the same object. A string literal in an extern inline function is the same object in different translation units.
However, if you define your function within the class definition, it is implicitly declared as inline function. That will allow you to include the class definition containing that inline function body multiple times in your program. Since the function has external linkage, any definition of it will refer to the same function (or more gory - to the same entity).
Gory details about my claim. First 3.5/5:
In addition, a member function, static data member, class or enumeration of class scope has external linkage if the name of the class has external linkage.
Then 3.5/4:
A name having namespace scope has external linkage if it is the name of [...] a named class (clause 9), or an unnamed class defined in a typedef declaration in which the class has the typedef name for linkage purposes.
This "name for linkage purposes" is this fun thing:
typedef struct { [...] } the_name;
Since now you have multiple definitions of the same entity in your programs, another thing of the ODR happens to restrict you. 3.2/5 follows with boring stuff.
There can be more than one definition of a class type (clause 9), enumeration type (7.2), inline function with external linkage (7.1.2) [...] in a program provided that each definition appears in a different translation unit, and provided the definitions satisfy the following requirements. Given such an entity named D defined in more than one translation unit, then
each definition of D shall consist of the same sequence of tokens; and
in each definition of D, corresponding names, looked up according to 3.4, shall refer to an entity defined within the definition of D, or shall refer to the same entity, after overload resolution (13.3) and after matching of partial template specialization (14.8.3) [...]
I cut off some unimportant stuff now. The above are the two important one to remember about inline functions. If you define an extern inline function multiple times, but do define it differently, or if you define it and names used within it resolve to different entities, then you are doing undefined behavior.
The rule that the function has to be defined in every TU in which it is used is easy to remember. And that it is the same is also easy to remember. But what about that name resolution thingy? Here some example. Consider a static function assert_it:
static void assert_it() { [...] }
Now, since static will give it internal linkage, when you include it into multiple translation units, then each definition will define a different entity. This means that you are not allowed to use assert_it from an extern inline function that's going to be defined multiple times in the program: Because what happens is that the inline function will refer to one entity called assert_it in one TU, but to another entity of the same name in another TU. You will find that this all is boring theory and compilers won't probably complain, but i found this example in particular shows the relation between the ODR and entities.
What follows is getting back to your particular problem again.
Following are the same things:
struct A { void f() { } };
struct A { inline void f(); }; void A::f() { } // same TU!
But this one is different, since the function is non-inline. You will violate the ODR, since you have more than one definition of f if you include the header more than once
struct A { void f(); }; void A::f() { } // evil!
Now if you put inline on the declaration of f inside the class, but then omit defining it in the header, then you violate 3.2/3 (and 7.1.2/4 which says the same thing, just more elaborating), since the function isn't defined in that translation unit!
Note that in C (C99), inline has different semantics than in C++. If you create an extern inline function, you should first read some good paper (preferably the Standard), since those are really tricky in C (basically, any used inline-definition of a function will need another, non-inline function definition in another TU. static inline functions in C are easy to handle. They behave like any other function, apart of having the usual "inline substitution" hint. static inline in both C and C++ serve only as a inline-substitution hint. Since static will already create a different entity any time it's used (because of internal linkage), inline will just add the inline-substitution hint - not more.
Whether or not the method is actually inlined is at the sole discretion of the compiler. However the presence of the inline keyword will also affect the linkage of the method.
C++ linkage is not my specialty so I'll defer to the links for a better explanation.
http://publib.boulder.ibm.com/infocenter/zos/v1r9/index.jsp?topic=/com.ibm.zos.r9.cbclx01/inline_linkage.htm
http://en.wikipedia.org/wiki/Inline_function
Alternately you can just wait for litb to provide the gory details in an hour or so ;)
Point to note: when method is declared inline, its definition MUST be together with its declaration.
Regarding harshath.jr's answer, a method need not be declared inline if its definition has the "inline" keyword, and that definition is available in the same header, i.e.:
class foo
{
void bar();
};
inline void foo::bar()
{
...
}
This is useful for conditionally inlining a method depending on whether or not the build is "debug" or "release" like so:
// Header - foo.h
class foo
{
void bar(); // Conditionally inlined.
};
#ifndef FOO_DEBUG
# include "foo.inl"
#endif
The "inline" file could look like:
// Inline Functions/Methods - foo.inl
#ifndef FOO_DEBUG
# define FOO_INLINE inline
#else
# define FOO_INLINE
#endif
FOO_INLINE void foo::bar()
{
...
}
and the implementation could like the following:
// Implementation file - foo.cpp
#ifdef FOO_DEBUG
# include "foo.inl"
#endif
...
It's not exactly pretty but it has it's uses when aggressive inline becomes a debugging headache.