[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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [PATCH] doc: document extern-inline,
Paul Eggert <=