`#[inline]` section could use additional details

[jonathanstrong]

In trying to choose whether to use #[inline] on a function, I found the section in this book. However, here are several questions I had after reading it:

• Does #[inline] apply to all implementations of a function defined by a trait, if the trait's declaration of that function is annotated?
• Does #[inline] apply to an implementation of a trait function if the trait's declaration does not have an #[inline] annotation?
• Will rustc ever inline a function from another crate without #[inline]?
• Will rustc inline a function from another crate if it is annotated with #[inline]?
• In what types of situations would incorrectly using this annotation cause programs to be slower? What makes those uses of inline slower? I'm guessing it's related to keeping the instruction size small and cache-friendly, but I don't know for sure.

I volunteer to write the answers to these questions in polished form for the book and submit a pull request if someone can answer the substance of them here.

[Havvy]

Aww, I wrote a comment here and I thought it submitted, but apparently it didn't. I'll write a better one.

The first two questions should be answerable by the reference, but the latter three should not. #[inline] means the function is inline-hinted for the optimizer, but whether the optimizer actually uses said hint is up to it. Right now rustc does inline across crates (including keeping inline info in the crate metadata¹) but that's almost entirely an implementation detail even if it's what keeps the standard library fast so that you don't have to copy the function into your crate for optimization purposes.

For the actual reference information:

#[inline] on prototype functions (trait declarations and fn declarations in external blocks) does nothing, and should probably emit a warning. On a default implementation inside of a method, it applies, but does not apply to the overriding function. Functions in impls can put #[inline] on, just like normal functions.

As for when inline-hinting makes your program slower, you have the same level of understanding that I do. Really, when you care about it, you should be benchmarking to make sure that the inlining actually helps. Slapping it on and thinking it'll always help is bad thinking, and that's what is actually being warned against.

So if you want to add a PR, definitely state it's hinting that the access should be inlined, not that it will be, and that #[inline(always)] is an even stronger inline form. Or if you don't want to, I want to move #[cold] into that section and rename it to "Optimization Hints".

1: It currently even states so in the reference, but it shouldn't.

[jonathanstrong]

Cool - thanks for the info.

One question, you mention two types of prototype functions, the second being fn declarations in external blocks. What does that mean? I don't think I've encountered it before. I'm thinking it's like declaring a variable with let ahead of when it's assigned, but I don't know how you'd do that with a function.

Also - should I reorganize the text as part of an "Optimization Hints" section in my pull request? Happy to do so - it would just be a draft obviously.

[Havvy]

If you want to go for the re-organization yourself, go for it.

---

External blocks declare that there's functions with a specific names and signatures that will be linked in, but we don't have the implementation here. e.g.

extern "C" {
  // I have not used external blocks to know at all if this would be a
  // correct way to get C's strstr into scope. Don't copy this code.
  fn strstr(s1: *const char, 2: *const char);
}