bug-gnulib
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[PATCH] doc: document extern-inline


From: Paul Eggert
Subject: [PATCH] doc: document extern-inline
Date: Tue, 18 Jun 2013 14:24:08 -0700
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/20130514 Thunderbird/17.0.6

---
 ChangeLog              |  6 ++++
 doc/extern-inline.texi | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/gnulib.texi        |  3 ++
 m4/extern-inline.m4    | 14 +++-----
 4 files changed, 110 insertions(+), 9 deletions(-)
 create mode 100644 doc/extern-inline.texi

diff --git a/ChangeLog b/ChangeLog
index 0af59a5..5e4f02f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,11 @@
 2013-06-18  Paul Eggert  <address@hidden>
 
+       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.
+
        doc: chatter less
        * doc/Makefile (NEWEST_GNULIB_TEXI_FILE): New macro.
        (updated-stamp): Use it.  This causes 'make' to output just
diff --git a/doc/extern-inline.texi b/doc/extern-inline.texi
new file mode 100644
index 0000000..1519bc4
--- /dev/null
+++ b/doc/extern-inline.texi
@@ -0,0 +1,96 @@
address@hidden GNU extern-inline module documentation
+
address@hidden Copyright (C) 2013 Free Software Foundation, Inc.
+
address@hidden Permission is granted to copy, distribute and/or modify this 
document
address@hidden under the terms of the GNU Free Documentation License, Version 
1.3
address@hidden or any later version published by the Free Software Foundation;
address@hidden with no Invariant Sections, no Front-Cover Texts, and no 
Back-Cover
address@hidden Texts.  A copy of the license is included in the ``GNU Free
address@hidden Documentation License'' file as part of this distribution.
+
address@hidden Written by Paul Eggert.
+
address@hidden extern inline
address@hidden Extern inline functions
+
address@hidden extern inline
address@hidden inline
+
+The @code{extern-inline} module supports the use of C99-style
address@hidden 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,
address@hidden 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
address@hidden  If code is intended to portable to pre-C99 compilers,
address@hidden 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
address@hidden is not inlined its code will appear in the executable
+three times.
+
+To avoid this code bloat, @file{aaa.h} can do this:
+
address@hidden
+/* 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)
address@hidden
+  return i + 1;
address@hidden
+...
+_GL_INLINE_HEADER_END
address@hidden example
+
address@hidden
+and @file{aaa.c} can do this:
+
address@hidden
+/* aaa.c */
+#include <config.h>
+#define AAA_INLINE _GL_EXTERN_INLINE
+#include <aaa.h>
address@hidden example
+
address@hidden
+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
address@hidden 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.
+
address@hidden _GL_INLINE
address@hidden is a portable alternative to C99 plain @code{inline}.
+
address@hidden _GL_EXTERN_INLINE
address@hidden is a portable alternative to C99 @code{extern inline}.
+
address@hidden _GL_INLINE_HEADER_BEGIN
+Invoke @code{_GL_INLINE_HEADER_BEGIN} before all uses of
address@hidden in an include file.  If an include file includes
+other files, it is better to invoke this macro after including the
+other files.
+
address@hidden _GL_INLINE_HEADER_END
+Invoke @code{_GL_INLINE_HEADER_END} after all uses of
address@hidden in an include file.
diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index de39a44..1ff7720 100644
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -6679,6 +6679,7 @@ This list of functions is sorted according to the header 
that declares them.
 * Safe Allocation Macros::
 * Compile-time Assertions::
 * Integer Properties::
+* extern inline::
 * String Functions in C Locale::
 * Quoting::
 * error and progname::
@@ -6712,6 +6713,8 @@ This list of functions is sorted according to the header 
that declares them.
 
 @include intprops.texi
 
address@hidden extern-inline.texi
+
 @node String Functions in C Locale
 @section Character and String Functions in C Locale
 
diff --git a/m4/extern-inline.m4 b/m4/extern-inline.m4
index 94b46dd..4e801e3 100644
--- a/m4/extern-inline.m4
+++ b/m4/extern-inline.m4
@@ -8,15 +8,7 @@ dnl with or without modifications, as long as this notice is 
preserved.
 AC_DEFUN([gl_EXTERN_INLINE],
 [
   AH_VERBATIM([extern_inline],
-[/* _GL_INLINE is a portable alternative to ISO C99 plain 'inline'.
-   _GL_EXTERN_INLINE is a portable alternative to 'extern inline'.
-   _GL_INLINE_HEADER_BEGIN contains useful stuff to put
-     in an include file, before uses of _GL_INLINE.
-     It suppresses GCC's bogus "no previous prototype for 'FOO'" diagnostic,
-     when FOO is an inline function in the header; see
-     <http://gcc.gnu.org/bugzilla/show_bug.cgi?id=54113>.
-   _GL_INLINE_HEADER_END contains useful stuff to put
-     in the same include file, after uses of _GL_INLINE.
+[/* Please see the Gnulib manual for how to use these macros.
 
    Suppress extern inline with HP-UX cc, as it appears to be broken; see
    <http://lists.gnu.org/archive/html/bug-texinfo/2013-02/msg00030.html>.
@@ -59,6 +51,10 @@ AC_DEFUN([gl_EXTERN_INLINE],
 #  define _GL_INLINE_HEADER_CONST_PRAGMA \
      _Pragma ("GCC diagnostic ignored \"-Wsuggest-attribute=const\"")
 # endif
+  /* Suppress GCC's bogus "no previous prototype for 'FOO'"
+     and "no previous declaration for 'FOO'"  diagnostics,
+     when FOO is an inline function in the header; see
+     <http://gcc.gnu.org/bugzilla/show_bug.cgi?id=54113>.  */
 # define _GL_INLINE_HEADER_BEGIN \
     _Pragma ("GCC diagnostic push") \
     _Pragma ("GCC diagnostic ignored \"-Wmissing-prototypes\"") \
-- 
1.7.11.7




reply via email to

[Prev in Thread] Current Thread [Next in Thread]