doc/extern-inline.texi

   1 @c GNU extern-inline module documentation
   2
   3 @c Copyright (C) 2013-2016 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
   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
  21 @code{extern inline} functions so that the code still runs on pre-C99
  22 compilers.
  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
  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
  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 */
  48 #ifndef _GL_INLINE_HEADER_BEGIN
  49  #error "Please include config.h first."
  50 #endif
  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.
  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.
  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
  93 @code{_GL_INLINE} in an include file.  This suppresses some
  94 bogus warnings in GCC versions before 5.1.  If an include file includes
  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.