small functions defined in header files: inline or static?

Question

I have a number of small functions which are defined in a .h file. It is a small project (now) and I want to avoid the pain of having declarations and definitions separate, because they change all the time. To avoid multiply-defined symbols, I can either have them static or inline. What should be preferred and why?

I know it is in general bad practice to define functions in headers. You don't have to mention that in answers, this question is meant technically.

Solution 1

I'd use static inline, but static would work just as well.

extern and extern inline are out because you'd get multiple external definitions if the header is included in more than one translation unit, so you need to consider static, static inline and inline specification.

Heptic correctly states in his answer that most compilers consider functions for inlining regardless of whether inline is specified or not, ie the main impact of inline is its effect on linkage.

However, static definitions have internal linkage, so there's not much difference between static and static inline; I prefer static inline for function definitions in header files for purely stylistic reasons (rule of thumb: header files should only contain extern declarations, static const variable definitions and static inline function definitions).

inline without static or extern results in an inline definition, which the standard states (C99 6.7.4, §6)

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.

ie inline definitions should always be accompanied by external definitions, which is not what you're looking for.

Some more information about the subtleties of C99 inline semantics can be found in this answer, on the Clang homepage and the C99 Rationale (PDF).

Keep in mind that GCC will only use C99 semantics if -std=c99 or -std=gnu99 is present...

Solution 2

Since the question is about C (not C++), inline means that

1. You wish "that calls to the function be as fast as possible" (ISO9899-1999, 6.7.4(5)). The same paragraph also states that it is implementation-defined to which extent this suggestion is effective. In other words, it has little bearing and does not imply any inlining at all (in fact, non-inlining may quite possibly be faster due to instruction cache effects).
2. there are some restrictions and special cases in combination with extern (ISO9899-1999, 6.7.4(6), for example an inline funciton with external linkage must be defined in the same compilation unit, and an inline definition allows an extern definition elsewhere without an error (which is not necessarily a good thing, because the two functions need not be functionally equivalent, and it is unspecified which one the compiler uses at any time!).

The linker implications given by Heptic are required for C++, but not required by C (as far as I can tell). They are necessarily required by the "shall have the same address in all translation units" clause in ISO14882, 7.1.2(4). I am not aware of any similar clause in C99.
However, since the entirely different languages C and C++ usually go through the same C/C++ compiler and linker, it likely works identically for C, anyway.

So... how to answer your question? Use inline when you feel it's adequate. Be aware of the possible pitfalls of extern. Otherwise, leave it away and trust the compiler to do it right.

Comments

[Matt Joiner]

You neglected to explain why.

[m0skit0]

"inline is ambiguous and allows extern keyword as well, defeating your purpose."

[Christoph]

@Heptic: the wording of the standard is somewhat ambiguous, but as I understand it, the compiler is always free to completely ignore any inline definition and fall back to an external one, which will obviously fail if there isn't such a definition in another translation unit...

[Christoph]

@Heptic: my interpretation seems to be correct - see the accompanying example, ie C99 7.6.4 §8

[Christoph]

@Heptic: also, not all major compilers/linker work the way you describe - in addition to clang, gcc also respects C99 semantics if -std=c99 or -std=gnu99 is present...

[Heptic]

touche. C99 standards agree with you. I can't see any logic behind their decision, especially in light of gcc/c++/msvc doing it correct, but that's a separate issue.

[m0skit0]

I expanded my explanation, hope you can comment when you downvote, so I (we) can learn ;)

[Matt Joiner]

Not sure how valid this answer is. "Use inline when you feel it's adequate" suggests you might not use it, won't you get multiple definition errors at link time?

[Matt Joiner]

As discussed in other answers, inline doesn't have the meaning you infer in this answer.

[Damon]

@Matt Joiner: Possibly, it depends. What I'm saying is, there is not really a "right" or "wrong", for making something inline, in the same sense as there is no right nor wrong regarding whether you put a definition in a header or a source -- you can do one of these or both, and none is generally wrong, it's a design choice. Whether you run into trouble with a double definition (you're generally right about your concern!) is a different matter. There is certainly the ODR. But the headers may be included only once (we don't know), and there is #ifdef, if nothing else, in case...

[Damon]

... in case the OP really wants to put a definition into a header, but doesn't want it inlined (And then, there are compiler features (if portability is not strictly required) such as gnu_inline which totally change rules yet again.). Though that would probably require another extern declaration in the #else clause... not pretty, but ah well... In the end, one needs to choose the one thing that feels right.

[Fabian]

static inline implies that each translation unit gets its own copy of the function. This increases the size of the binary. inline make one function shared by all translation units. See also stackoverflow.com/questions/10847176