Mercurial > hg > octave-nkf > gnulib-hg
changeset 17435:a0d0b52b7d06
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.
author | Paul Eggert <eggert@cs.ucla.edu> |
---|---|
date | Tue, 18 Jun 2013 14:23:03 -0700 |
parents | 4e99d991c696 |
children | 54c2b89ac5ec |
files | ChangeLog doc/extern-inline.texi doc/gnulib.texi m4/extern-inline.m4 |
diffstat | 4 files changed, 110 insertions(+), 9 deletions(-) [+] |
line wrap: on
line diff
--- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,11 @@ 2013-06-18 Paul Eggert <eggert@cs.ucla.edu> + 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
new file mode 100644 --- /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.
--- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -6679,6 +6679,7 @@ * Safe Allocation Macros:: * Compile-time Assertions:: * Integer Properties:: +* extern inline:: * String Functions in C Locale:: * Quoting:: * error and progname:: @@ -6712,6 +6713,8 @@ @include intprops.texi +@include extern-inline.texi + @node String Functions in C Locale @section Character and String Functions in C Locale
--- a/m4/extern-inline.m4 +++ b/m4/extern-inline.m4 @@ -8,15 +8,7 @@ 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 @@ # 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\"") \