Documentation for #[inline] in the reference doesn't align with external resources

[saethlin]

The current documentation for #[inline] places huge emphasis on its effect as an inlining hint. I was recently referred to the reference when I tried to inform another user that its primary effect is enabling cross-crate inlining of non-generic functions. I'm not sure if this lack of documentation is just an oversight (which I'm happy to correct with a PR) or if this is deliberate because the cross-crate inlining effect is planned to be removed, or if the hint is guaranteed, but the codegen difference isn't.

I'm particularly concerned, because this effect is well-known in resources outside of the reference:
https://matklad.github.io/2021/07/09/inline-in-rust.html
rust-lang/hashbrown#119 (comment)

[ehuss]

It is currently deliberate. There are no guarantees as to what inline does. Implementations are free to ignore it if they desire.

[saethlin]

Ah, so people are wrong to read the reference as indicating that #[inline] is a hint to the inliner? It sounds like the reference should say that if the attribute does anything, it suggests inlining, and implementations may do this by whatever means they see fit.

Or maybe this deserves to be in a Note:, after all there is already one about the rustc implementation on this attribute.

[ehuss]

Maybe I'm not understanding, but inline is a hint to the inliner. The compiler is free to use the suggestion or not.

And there is a note about it:

Note: #[inline] in every form is a hint, with no requirements on the language to place a copy of the attributed function in the caller.

[saethlin]

My concern is that I told a user about the alteration to the way rustc does codegen, and they tried to tell me I was wrong by citing the reference. So where in that is the problem?

[ehuss]

Maybe I'm not clear, but is your question "does inline cause cross-crate inlining"? Then the answer from the language perspective is "it is up to the implementation how it behaves". From the perspective of how rustc+llvm is implemented internally, then I think the link you posted from Alex is how I remember it working. But that is not something I would rely on, nor something we would document at this time.

[saethlin]

I know what #[inline] does in rustc. My concern is that people are going looking for documentation for it, finding the reference, and concluding that what the reference mentions is the extent of what rustc does. That is, just a hint to the LLVM inliner, and ergo it is gratuitous to put the attribute on small functions, when the exact opposite is true.

I think it would be a nice improvement to make the language in the reference either more vague, such as amending

Note: #[inline] in every form is a hint, with no requirements on the language to place a copy of the attributed function in the caller.

To

Note: #[inline] in every form is a hint. Implementations may significantly adapt their code generation model to accommodate the hint, or ignore it entirely. Refer to your implementation's documentation for details.

Or more specific, mentioning what rustc does, or pointing to some rustc documentation for this attribute (which as far as I know, doesn't exist, why is why people are in the reference to begin with).

[ehuss]

gratuitous to put the attribute on small functions, when the exact opposite is true.

It may be gratuitous. I wouldn't place the attribute on a function unless benchmarking indicated it was warranted.

Refer to your implementation's documentation for details.

As I mentioned, I think it is unlikely we would want to document the specifics of rustc (here or elsewhere). However, you can perhaps contact the compiler team if they would be interested in specifying its behavior.

[riking]

+1 the effect on codegen blowup should be documented properly