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.
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.
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(); }
Here's the body of main.cpp
#include "Header.h"
int main()
{
auto f = Foo();
f.bar();
return 0;
}
Here's the body of Header.h
class Foo {
public:
void bar();
};
Here's the body of Source.cpp
#include <iostream>
class Foo {
public:
void bar() {
std::cout << "Foo.bar() called\n";
}
};
void t() {
auto f = Foo();
f.bar(); // If this line isn't here, the project won't compile
}
When I comment out f.bar(); in Source.cpp, I receive the following error upon compilation. It's telling me that f.bar() in main() is unresolved:
Error LNK2019 unresolved external symbol "public: void __thiscall
Foo::bar(void)" (?bar#Foo##QAEXXZ) referenced in function _main ...
I understand that it's common to define methods outside of class scope, and indeed the following version of Source.cpp compiles successfully--
#include <iostream>
#include "Header.h"
void Foo::bar() {
std::cout << "Foo.bar() called\n";
}
Nonetheless, I don't understand what's wrong with the original version. It feels like something mysterious and magical is going on that I don't fully understand.
This is an ODR violation either way, because the class Foo as defined in the header, and the class Foo as defined in the cpp file are not token by token identical.
out of line definition of bar should look like
#include <iostream>
#include "Header.h"
void Foo::bar() {
std::cout << "Foo.bar() called\n";
}
Note that ODR violations are 'no diagnostics required'
(this is why one of the examples compiles, the compiler can't always detect ODR violations)
The best way to not accidentally create errors like this is to always include the header-file in the file/files where you implement the methods.
When we are talking about good practices, don't forget the include-guard in the header-file.
If a method is short enough to be inline defined, (style may vary, but for me that means a short oneliner), then that inline definition need to be present in the header-file, so that the compiler sees an identical type every time it encounters it.
Your original program violates the One Definition Rule (ODR), defined in C++14, 3.2. The relevant paragraph is number 6:
There can be more than one definition of a class type [...] 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 name D defined in more than one translation unit, then
each definition of D shall consist of the same sequence of tokens; and
[...]
You have two translation units: main.cpp with all its header files (including Header.h), and Source.cpp with all its header files (which do not include Header.h). Both translation units contain a definition of the class ::Foo: main.cpp contains the one from Header.h, and Source.cpp has its own.
However, the two do not consist of the same sequence of tokens. The one in Source.cpp contains an inline function definition.
The reason for having one definition of a class in a header and only getting it by including this header is two-fold:
You save the effort of duplicating it, and more importantly, finding every duplicate if you have to change it.
Barring preprocessor shenanigans, with there being only one textual form of the definition, you cannot run afoul of the ODR.
Note that ODR violations are "no diagnostic required" - in your case you get an error, but as you saw, the error disappears if you call the function in Source.cpp. That doesn't mean your program became correct; it just means that the compiler was no longer capable of discovering the error; nonetheless, very strange behavior could occur. Your program has undefined behavior.
Take a look at the C++ standard 9.3.2 (n4296):
" ... A member function may be defined (8.4) in its class definition, in which case it is an inline member function
(7.1.2), or it may be defined outside of its class definition if it has already been declared but not defined
in its class definition. A member function definition that appears outside of the class definition shall appear
in a namespace scope enclosing the class definition. Except for member function definitions that appear
outside of a class definition, and except for explicit specializations of member functions of class templates
and member function templates (14.7) appearing outside of the class definition, a member function shall not
be redeclared ..."
& 9.3.3 :
" ...An inline member function (whether static or non-static) may also be defined outside of its class definition
provided either its declaration in the class definition or its definition outside of the class definition declares
the function as inline.[ Note: Member functions of a class in namespace scope have the linkage of that
class. Member functions of a local class (9.8) have no linkage. See 3.5. —end note ] ..."
Since bar() is defined inside Foo { }; it is implicitly inline.
I believe taking the above clauses into consideration together implies that Foo::bar has local linkage in Source.cpp & is not visible to anyone else. What I find confusing is that calling f.bar() changes the linkage allowing your other example to compile.
Compiler take the cpp files one by one, there's no way the compiler will remember what else he compiled in another file
main.cpp - include header. Header contains a class declaration. main.obj expects that foo() will be implemented as a separate symbol available at linking time. Done, write the object file and forget
Source.cpp redeclare the class without including the header. As such, the compiler cannot complain of the double declaration. As in the Source.cpp declaration the foo method is implemented inline, the compiler (not knowing anything about what main expects) does not generate a linkage symbol for the method, Done, write the object and forget
linker loads both objects, see that the 'main.obj' needs a linkage symbol for the foo method, searches everywhere and cannot find one - because the Source.obj does not contain one - the compiler was instructed the method will be inline.
Makes sense?
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()
}
Suppose I have
Base.h
class Base
{
virtual void foo() {...}
};
Derived1.h
class Derived1 : public Base
{
virtual void foo() {...}
};
Derived2.h
class Derived2 : public Base
{
virtual void foo() {...}
};
Header Derived1.h is included in multiple source files and Derived1 class is also used through Base interface. Since foo is virtual and is used polymorphic it can not be inlined. So it will be compiled in multiple obj files. How does linker then resolve this situation?
Member functions defined within class definition are implicitly inline(C++03 7.1.2.3).
Whether the function body actually gets inlined at point of calling is immaterial. But inline allows you to have multiple definitions of a function as long as all the definitions are same(which is disallowed by One definition rule)(C++03 7.1.2.2). The standard mandates that the linker should be able to link to (one or)many of these definitions.(C++03 7.1.2.4).
How does the linker do this?
The standard provisions for this by:
It mandates that the function definition should be present in each translation unit. All the linker has to do is link to the definition found in that translation unit.
It mandates that all definitions of this function should be exactly same, this removes any ambiguity of linking to a particular definition, if different definitions were to exist.
C++03 7.1.2 Function specifiers:
Para 2:
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.
Para 3:
A function defined within a class definition is an inline function. The inline specifier shall not appear on a block scope function declaration
Para 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).