Mercurial > gnulib
annotate doc/extern-inline.texi @ 40057:b06060465f09
maint: Run 'make update-copyright'
| author | Paul Eggert <eggert@cs.ucla.edu> |
|---|---|
| date | Tue, 01 Jan 2019 00:25:11 +0100 |
| parents | 10eb9086bea0 |
| children |
| rev | line source |
|---|---|
| 17424 | 1 @c GNU extern-inline module documentation |
| 2 | |
|
40057
b06060465f09
maint: Run 'make update-copyright'
Paul Eggert <eggert@cs.ucla.edu>
parents:
19484
diff
changeset
|
3 @c Copyright (C) 2013-2019 Free Software Foundation, Inc. |
| 17424 | 4 |
| 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. | |
| 11 | |
| 12 @c Written by Paul Eggert. | |
| 13 | |
| 14 @node extern inline | |
| 15 @section Extern inline functions | |
| 16 | |
| 17 @cindex extern inline | |
| 18 @cindex inline | |
| 19 | |
| 20 The @code{extern-inline} module supports the use of C99-style | |
|
18812
06504a1de0ad
Target a C99 subset, not a C89 subset
Paul Eggert <eggert@cs.ucla.edu>
parents:
18626
diff
changeset
|
21 @code{extern inline} functions so that the code still runs on |
|
06504a1de0ad
Target a C99 subset, not a C89 subset
Paul Eggert <eggert@cs.ucla.edu>
parents:
18626
diff
changeset
|
22 compilers that do not support this feature correctly. |
| 17424 | 23 |
| 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. | |
| 29 | |
| 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 | |
|
18812
06504a1de0ad
Target a C99 subset, not a C89 subset
Paul Eggert <eggert@cs.ucla.edu>
parents:
18626
diff
changeset
|
34 @file{aaa.h}. If code is intended to portable to non-C99 compilers, |
| 17424 | 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 | |
| 41 three times. | |
| 42 | |
| 43 To avoid this code bloat, @file{aaa.h} can do this: | |
| 44 | |
| 45 @example | |
| 46 /* aaa.h */ | |
| 47 /* #include any other headers here */ | |
|
17473
1f9070ef79b0
headers: check that _GL_INLINE_HEADER_BEGIN is defined
Paul Eggert <eggert@cs.ucla.edu>
parents:
17424
diff
changeset
|
48 #ifndef _GL_INLINE_HEADER_BEGIN |
|
1f9070ef79b0
headers: check that _GL_INLINE_HEADER_BEGIN is defined
Paul Eggert <eggert@cs.ucla.edu>
parents:
17424
diff
changeset
|
49 #error "Please include config.h first." |
|
1f9070ef79b0
headers: check that _GL_INLINE_HEADER_BEGIN is defined
Paul Eggert <eggert@cs.ucla.edu>
parents:
17424
diff
changeset
|
50 #endif |
| 17424 | 51 _GL_INLINE_HEADER_BEGIN |
| 52 #ifndef AAA_INLINE | |
| 53 # define AAA_INLINE _GL_INLINE | |
| 54 #endif | |
| 55 ... | |
| 56 AAA_INLINE int | |
| 57 aaa_fun (int i) | |
| 58 @{ | |
| 59 return i + 1; | |
| 60 @} | |
| 61 ... | |
| 62 _GL_INLINE_HEADER_END | |
| 63 @end example | |
| 64 | |
| 65 @noindent | |
| 66 and @file{aaa.c} can do this: | |
| 67 | |
| 68 @example | |
| 69 /* aaa.c */ | |
| 70 #include <config.h> | |
| 71 #define AAA_INLINE _GL_EXTERN_INLINE | |
| 72 #include <aaa.h> | |
| 73 @end example | |
| 74 | |
| 75 @noindent | |
| 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. | |
|
18812
06504a1de0ad
Target a C99 subset, not a C89 subset
Paul Eggert <eggert@cs.ucla.edu>
parents:
18626
diff
changeset
|
80 Non-C99 compilers that are compatible with GCC use GCC-specific syntax |
|
06504a1de0ad
Target a C99 subset, not a C89 subset
Paul Eggert <eggert@cs.ucla.edu>
parents:
18626
diff
changeset
|
81 to accomplish the same ends. Other non-C99 compilers use @code{static |
| 17424 | 82 inline} so they suffer from code bloat, but they are not mainline |
| 83 platforms and will die out eventually. | |
| 84 | |
| 85 @findex _GL_INLINE | |
| 86 @code{_GL_INLINE} is a portable alternative to C99 plain @code{inline}. | |
| 87 | |
| 88 @findex _GL_EXTERN_INLINE | |
| 89 @code{_GL_EXTERN_INLINE} is a portable alternative to C99 @code{extern inline}. | |
| 90 | |
| 91 @findex _GL_INLINE_HEADER_BEGIN | |
| 92 Invoke @code{_GL_INLINE_HEADER_BEGIN} before all uses of | |
|
17978
144717f4f8b0
extern-inline: no need for workaround in GCC 5.1
Paul Eggert <eggert@cs.ucla.edu>
parents:
17848
diff
changeset
|
93 @code{_GL_INLINE} in an include file. This suppresses some |
|
144717f4f8b0
extern-inline: no need for workaround in GCC 5.1
Paul Eggert <eggert@cs.ucla.edu>
parents:
17848
diff
changeset
|
94 bogus warnings in GCC versions before 5.1. If an include file includes |
| 17424 | 95 other files, it is better to invoke this macro after including the |
| 96 other files. | |
| 97 | |
| 98 @findex _GL_INLINE_HEADER_END | |
| 99 Invoke @code{_GL_INLINE_HEADER_END} after all uses of | |
| 100 @code{_GL_INLINE} in an include file. |