doc/extern-inline.texi

   1 @c GNU extern-inline module documentation
   2
   3 @c Copyright (C) 2013-2014 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.  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.