doc/extern-inline.texi

   1 @c GNU extern-inline module documentation
   2
   3 @c Copyright (C) 2013 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 _GL_INLINE_HEADER_BEGIN
  49 #ifndef AAA_INLINE
  50 # define AAA_INLINE _GL_INLINE
  51 #endif
  52 ...
  53 AAA_INLINE int
  54 aaa_fun (int i)
  55 @{
  56   return i + 1;
  57 @}
  58 ...
  59 _GL_INLINE_HEADER_END
  60 @end example
  61
  62 @noindent
  63 and @file{aaa.c} can do this:
  64
  65 @example
  66 /* aaa.c */
  67 #include <config.h>
  68 #define AAA_INLINE _GL_EXTERN_INLINE
  69 #include <aaa.h>
  70 @end example
  71
  72 @noindent
  73 whereas @file{bbb.c} and @file{ccc.c} can include @file{aaa.h} in the
  74 usual way.  C99 compilers expand @code{AAA_INLINE} to C99-style
  75 @code{inline} usage, where @code{aaa_fun} is declared @code{extern
  76 inline} in @file{aaa.c} and plain @code{inline} in other modules.
  77 Pre-C99 compilers that are compatible with GCC use GCC-specific syntax
  78 to accomplish the same ends.  Other pre-C99 compilers use @code{static
  79 inline} so they suffer from code bloat, but they are not mainline
  80 platforms and will die out eventually.
  81
  82 @findex _GL_INLINE
  83 @code{_GL_INLINE} is a portable alternative to C99 plain @code{inline}.
  84
  85 @findex _GL_EXTERN_INLINE
  86 @code{_GL_EXTERN_INLINE} is a portable alternative to C99 @code{extern inline}.
  87
  88 @findex _GL_INLINE_HEADER_BEGIN
  89 Invoke @code{_GL_INLINE_HEADER_BEGIN} before all uses of
  90 @code{_GL_INLINE} in an include file.  If an include file includes
  91 other files, it is better to invoke this macro after including the
  92 other files.
  93
  94 @findex _GL_INLINE_HEADER_END
  95 Invoke @code{_GL_INLINE_HEADER_END} after all uses of
  96 @code{_GL_INLINE} in an include file.