From 68f90afdb82204c27a50e7bce169d2b3795a1ddd Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Tue, 18 Jun 2013 14:23:03 -0700 Subject: 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/extern-inline.texi | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 doc/extern-inline.texi (limited to 'doc/extern-inline.texi') 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 +#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. -- cgit v1.2.1