# HG changeset patch # User Paul Eggert # Date 1371590583 25200 # Node ID a0d0b52b7d066c89f71e5779a2f8c140a4c6462e # Parent 4e99d991c6965ee012d1c84b0096018a202fc816 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. diff -r 4e99d991c696 -r a0d0b52b7d06 ChangeLog --- a/ChangeLog Tue Jun 18 14:18:36 2013 -0700 +++ b/ChangeLog Tue Jun 18 14:23:03 2013 -0700 @@ -1,5 +1,11 @@ 2013-06-18 Paul Eggert + 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 -r 4e99d991c696 -r a0d0b52b7d06 doc/extern-inline.texi --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/extern-inline.texi Tue Jun 18 14:23:03 2013 -0700 @@ -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 +#define AAA_INLINE _GL_EXTERN_INLINE +#include +@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. diff -r 4e99d991c696 -r a0d0b52b7d06 doc/gnulib.texi --- a/doc/gnulib.texi Tue Jun 18 14:18:36 2013 -0700 +++ b/doc/gnulib.texi Tue Jun 18 14:23:03 2013 -0700 @@ -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 diff -r 4e99d991c696 -r a0d0b52b7d06 m4/extern-inline.m4 --- a/m4/extern-inline.m4 Tue Jun 18 14:18:36 2013 -0700 +++ b/m4/extern-inline.m4 Tue Jun 18 14:23:03 2013 -0700 @@ -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 - . - _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 . @@ -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 + . */ # define _GL_INLINE_HEADER_BEGIN \ _Pragma ("GCC diagnostic push") \ _Pragma ("GCC diagnostic ignored \"-Wmissing-prototypes\"") \