1 @c GNU extern-inline module documentation
3 @c Copyright (C) 2013 Free Software Foundation, Inc.
5 @c Permission is granted to copy, distribute and/or modify this document
6 @c under the terms of the GNU Free Documentation License, Version 1.3
7 @c or any later version published by the Free Software Foundation;
8 @c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
9 @c Texts. A copy of the license is included in the ``GNU Free
10 @c Documentation License'' file as part of this distribution.
12 @c Written by Paul Eggert.
15 @section Extern inline functions
20 The @code{extern-inline} module supports the use of C99-style
21 @code{extern inline} functions so that the code still runs on pre-C99
24 C code ordinarily should not use @code{inline}. Typically it is
25 better to let the compiler figure out whether to inline, as compilers
26 are pretty good about optimization nowadays. In this sense,
27 @code{inline} is like @code{register}, another keyword that is
28 typically no longer needed.
30 Functions defined (not merely declared) in headers are an exception,
31 as avoiding @code{inline} would commonly cause problems for these
32 functions. Suppose @file{aaa.h} defines the function @code{aaa_fun},
33 and @file{aaa.c}, @file{bbb.c} and @file{ccc.c} all include
34 @file{aaa.h}. If code is intended to portable to pre-C99 compilers,
35 @code{aaa_fun} cannot be declared with the C99 @code{inline} keyword.
36 This problem cannot be worked around by making @code{aaa_fun} an
37 ordinary function, as it would be defined three times with external
38 linkage and the definitions would clash. Although @code{aaa_fun}
39 could be a static function, with separate compilation if
40 @code{aaa_fun} is not inlined its code will appear in the executable
43 To avoid this code bloat, @file{aaa.h} can do this:
47 /* #include any other headers here */
48 #ifndef _GL_INLINE_HEADER_BEGIN
49 #error "Please include config.h first."
51 _GL_INLINE_HEADER_BEGIN
53 # define AAA_INLINE _GL_INLINE
66 and @file{aaa.c} can do this:
71 #define AAA_INLINE _GL_EXTERN_INLINE
76 whereas @file{bbb.c} and @file{ccc.c} can include @file{aaa.h} in the
77 usual way. C99 compilers expand @code{AAA_INLINE} to C99-style
78 @code{inline} usage, where @code{aaa_fun} is declared @code{extern
79 inline} in @file{aaa.c} and plain @code{inline} in other modules.
80 Pre-C99 compilers that are compatible with GCC use GCC-specific syntax
81 to accomplish the same ends. Other pre-C99 compilers use @code{static
82 inline} so they suffer from code bloat, but they are not mainline
83 platforms and will die out eventually.
86 @code{_GL_INLINE} is a portable alternative to C99 plain @code{inline}.
88 @findex _GL_EXTERN_INLINE
89 @code{_GL_EXTERN_INLINE} is a portable alternative to C99 @code{extern inline}.
91 @findex _GL_INLINE_HEADER_BEGIN
92 Invoke @code{_GL_INLINE_HEADER_BEGIN} before all uses of
93 @code{_GL_INLINE} in an include file. If an include file includes
94 other files, it is better to invoke this macro after including the
97 @findex _GL_INLINE_HEADER_END
98 Invoke @code{_GL_INLINE_HEADER_END} after all uses of
99 @code{_GL_INLINE} in an include file.