doc: document extern-inline

* doc/extern-inline.texi: New file.
* doc/gnulib.texi (alloca-opt): Include it.
* m4/extern-inline.m4: Move some comments to documentation,
and others closer to what they describe.

1 files changed, 96 insertions, 0 deletions

diff --git a/doc/extern-inline.texi b/doc/extern-inline.texi
new file mode 100644
index 0000000000..1519bc4a0d
--- /dev/null
+++ b/doc/extern-inline.texi
@@ -0,0 +1,96 @@
+@c GNU extern-inline module documentation
+
+@c Copyright (C) 2013 Free Software Foundation, Inc.
+
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3
+@c or any later version published by the Free Software Foundation;
+@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+@c Texts.  A copy of the license is included in the ``GNU Free
+@c Documentation License'' file as part of this distribution.
+
+@c Written by Paul Eggert.
+
+@node extern inline
+@section Extern inline functions
+
+@cindex extern inline
+@cindex inline
+
+The @code{extern-inline} module supports the use of C99-style
+@code{extern inline} functions so that the code still runs on pre-C99
+compilers.
+
+C code ordinarily should not use @code{inline}.  Typically it is
+better to let the compiler figure out whether to inline, as compilers
+are pretty good about optimization nowadays.  In this sense,
+@code{inline} is like @code{register}, another keyword that is
+typically no longer needed.
+
+Functions defined (not merely declared) in headers are an exception,
+as avoiding @code{inline} would commonly cause problems for these
+functions.  Suppose @file{aaa.h} defines the function @code{aaa_fun},
+and @file{aaa.c}, @file{bbb.c} and @file{ccc.c} all include
+@file{aaa.h}.  If code is intended to portable to pre-C99 compilers,
+@code{aaa_fun} cannot be declared with the C99 @code{inline} keyword.
+This problem cannot be worked around by making @code{aaa_fun} an
+ordinary function, as it would be defined three times with external
+linkage and the definitions would clash.  Although @code{aaa_fun}
+could be a static function, with separate compilation if
+@code{aaa_fun} is not inlined its code will appear in the executable
+three times.
+
+To avoid this code bloat, @file{aaa.h} can do this:
+
+@example
+/* aaa.h */
+/* #include any other headers here */
+_GL_INLINE_HEADER_BEGIN
+#ifndef AAA_INLINE
+# define AAA_INLINE _GL_INLINE
+#endif
+...
+AAA_INLINE int
+aaa_fun (int i)
+@{
+  return i + 1;
+@}
+...
+_GL_INLINE_HEADER_END
+@end example
+
+@noindent
+and @file{aaa.c} can do this:
+
+@example
+/* aaa.c */
+#include <config.h>
+#define AAA_INLINE _GL_EXTERN_INLINE
+#include <aaa.h>
+@end example
+
+@noindent
+whereas @file{bbb.c} and @file{ccc.c} can include @file{aaa.h} in the
+usual way.  C99 compilers expand @code{AAA_INLINE} to C99-style
+@code{inline} usage, where @code{aaa_fun} is declared @code{extern
+inline} in @file{aaa.c} and plain @code{inline} in other modules.
+Pre-C99 compilers that are compatible with GCC use GCC-specific syntax
+to accomplish the same ends.  Other pre-C99 compilers use @code{static
+inline} so they suffer from code bloat, but they are not mainline
+platforms and will die out eventually.
+
+@findex _GL_INLINE
+@code{_GL_INLINE} is a portable alternative to C99 plain @code{inline}.
+
+@findex _GL_EXTERN_INLINE
+@code{_GL_EXTERN_INLINE} is a portable alternative to C99 @code{extern inline}.
+
+@findex _GL_INLINE_HEADER_BEGIN
+Invoke @code{_GL_INLINE_HEADER_BEGIN} before all uses of
+@code{_GL_INLINE} in an include file.  If an include file includes
+other files, it is better to invoke this macro after including the
+other files.
+
+@findex _GL_INLINE_HEADER_END
+Invoke @code{_GL_INLINE_HEADER_END} after all uses of
+@code{_GL_INLINE} in an include file.