doc/extern-inline.texi

   1 @c GNU extern-inline module documentation
   2
   3 @c Copyright (C) 2013--2020 Free Software Foundation, Inc.
   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 or
   7 @c any later version published by the Free Software Foundation; with no
   8 @c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
   9 @c copy of the license is at <https://www.gnu.org/licenses/fdl-1.3.en.html>.
  10
  11 @c Written by Paul Eggert.
  12
  13 @node extern inline
  14 @section Extern inline functions
  15
  16 @cindex extern inline
  17 @cindex inline
  18
  19 The @code{extern-inline} module supports the use of C99-style
  20 @code{extern inline} functions so that the code still runs on
  21 compilers that do not support this feature correctly.
  22
  23 C code ordinarily should not use @code{inline}.  Typically it is
  24 better to let the compiler figure out whether to inline, as compilers
  25 are pretty good about optimization nowadays.  In this sense,
  26 @code{inline} is like @code{register}, another keyword that is
  27 typically no longer needed.
  28
  29 Functions defined (not merely declared) in headers are an exception,
  30 as avoiding @code{inline} would commonly cause problems for these
  31 functions.  Suppose @file{aaa.h} defines the function @code{aaa_fun},
  32 and @file{aaa.c}, @file{bbb.c} and @file{ccc.c} all include
  33 @file{aaa.h}.  If code is intended to portable to non-C99 compilers,
  34 @code{aaa_fun} cannot be declared with the C99 @code{inline} keyword.
  35 This problem cannot be worked around by making @code{aaa_fun} an
  36 ordinary function, as it would be defined three times with external
  37 linkage and the definitions would clash.  Although @code{aaa_fun}
  38 could be a static function, with separate compilation if
  39 @code{aaa_fun} is not inlined its code will appear in the executable
  40 three times.
  41
  42 To avoid this code bloat, @file{aaa.h} can do this:
  43
  44 @example
  45 /* aaa.h */
  46 /* #include any other headers here */
  47 #ifndef _GL_INLINE_HEADER_BEGIN
  48  #error "Please include config.h first."
  49 #endif
  50 _GL_INLINE_HEADER_BEGIN
  51 #ifndef AAA_INLINE
  52 # define AAA_INLINE _GL_INLINE
  53 #endif
  54 ...
  55 AAA_INLINE int
  56 aaa_fun (int i)
  57 @{
  58   return i + 1;
  59 @}
  60 ...
  61 _GL_INLINE_HEADER_END
  62 @end example
  63
  64 @noindent
  65 and @file{aaa.c} can do this:
  66
  67 @example
  68 /* aaa.c */
  69 #include <config.h>
  70 #define AAA_INLINE _GL_EXTERN_INLINE
  71 #include <aaa.h>
  72 @end example
  73
  74 @noindent
  75 whereas @file{bbb.c} and @file{ccc.c} can include @file{aaa.h} in the
  76 usual way.  C99 compilers expand @code{AAA_INLINE} to C99-style
  77 @code{inline} usage, where @code{aaa_fun} is declared @code{extern
  78 inline} in @file{aaa.c} and plain @code{inline} in other modules.
  79 Non-C99 compilers that are compatible with GCC use GCC-specific syntax
  80 to accomplish the same ends.  Other non-C99 compilers use @code{static
  81 inline} so they suffer from code bloat, but they are not mainline
  82 platforms and will die out eventually.
  83
  84 @findex _GL_INLINE
  85 @code{_GL_INLINE} is a portable alternative to C99 plain @code{inline}.
  86
  87 @findex _GL_EXTERN_INLINE
  88 @code{_GL_EXTERN_INLINE} is a portable alternative to C99 @code{extern inline}.
  89
  90 @findex _GL_INLINE_HEADER_BEGIN
  91 Invoke @code{_GL_INLINE_HEADER_BEGIN} before all uses of
  92 @code{_GL_INLINE} in an include file.  This suppresses some
  93 bogus warnings in GCC versions before 5.1.  If an include file includes
  94 other files, it is better to invoke this macro after including the
  95 other files.
  96
  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.