This is an archive of the discontinued LLVM Phabricator instance.

[AttrDocs]: document gnu_inline function attribute
ClosedPublic

Authored by nickdesaulniers on Aug 23 2018, 3:30 PM.

Diff Detail

Repository
rL LLVM

Event Timeline

  • link to correct doc
  • explicitly mention extern inline

Thanks for taking the time to write documentation.

The phrase "C89 convention" is misleading; the original ISO C standard doesn't define the inline keyword at all. Maybe something along the lines of "GNU inline extension". And maybe mention it's the default with -std=gnu89.

  • s/c89/GNU inline extension/g and mention -std=gnu89/-fgnu89-inline
rsmith added inline comments.Aug 27 2018, 5:34 PM
include/clang/Basic/AttrDocs.td
3514–3516 ↗(On Diff #162761)

This description is neither entirely correct nor complete. gnu_inline means:

  • If any declaration that is declared inline is not declared extern, then the inline keyword is just a hint (note that this is different from the behavior of inline in both C99 inline semantics and C++ inline semantics)
  • If all declarations that are declared inline are also declared extern, then the function body is present only for inlining and no out-of-line version is emitted

And in particular as special cases, static inline emits an out-of-line version if needed, a plain inline definition emits an out-of-line version always, and an extern inline definition (in a header) followed by a (non-extern) inline declaration in a source file emits an out-of-line version of the function in that source file but provides the function body for inlining to all includers of the header.

Please capitalize the C in C99.

3518–3522 ↗(On Diff #162761)

It would make sense to also mention __GNUC_GNU_INLINE__ here, and that exactly one of these two macros will be defined for any compilation (although the macros are meaningless in C++ and should not be used there).

3524 ↗(On Diff #162761)

This is the default behavior for all pre-C99 C compilations, notably including -std=c89 (and -std=c94).

  • Take rsmith's sugguested wording. Add info about GNUC_STDC_INLINE.
nickdesaulniers marked 3 inline comments as done.Aug 28 2018, 11:08 AM
rsmith added inline comments.Aug 29 2018, 2:38 PM
include/clang/Basic/AttrDocs.td
3518 ↗(On Diff #162908)

Might be useful to be a bit more explicit about how it differs:

[...] is just a hint. In particular, an out-of-line definition is still emitted for a function with external linkage even if all call sites are inlined, unlike in C99 inline semantics and C++ inline semantics.

3524 ↗(On Diff #162908)

Maybe replace the "And in particular as special cases," with "Some important consequences:"

3536 ↗(On Diff #162908)

I'd add: "It is unspecified which macro is defined in a C++ compilation."

(In practice, Clang always defines the GNU_INLINE macro, as do very old versions of GCC. More recent versions of GCC define GNU_INLINE in C++98 mode and STDC_INLINE in C++11 mode onwards, despite C++98 and C++11 having identical inline semantics. I don't think we want to give any guarantees about our behavior here.)

rsmith accepted this revision.Aug 29 2018, 2:38 PM
This revision is now accepted and ready to land.Aug 29 2018, 2:38 PM
  • link to correct doc
  • explicitly mention extern inline
  • s/c89/GNU inline extension/g and mention -std=gnu89/-fgnu89-inline
  • Take rsmith's sugguested wording. Add info about GNUC_STDC_INLINE.
  • some final touches recommended by rsmith
nickdesaulniers marked 3 inline comments as done.Aug 29 2018, 3:49 PM

Looks good, thanks for improving our documentation!

This revision was automatically updated to reflect the committed changes.

BTW, seems like these docs have tests that weren't updated. Fixed with rL341002, but please take a look if that's not the right fix.