Add -Z hint-mostly-unused to tell rustc that most of a crate will go unused

[joshtriplett]

This hint allows the compiler to optimize its operation based on this assumption, in order to compile faster. This is a hint, and does not guarantee any particular behavior.

This option can substantially speed up compilation if applied to a large dependency where the majority of the dependency does not get used. This flag may slow down compilation in other cases.

Currently, this option makes the compiler defer as much code generation as possible from functions in the crate, until later crates invoke those functions. Functions that never get invoked will never have code generated for them. For instance, if a crate provides thousands of functions, but only a few of them will get called, this flag will result in the compiler only doing code generation for the called functions. (This uses the same mechanisms as cross-crate inlining of functions.) This does not affect extern functions, or functions marked as #[inline(never)].

This option has already existed in nightly as -Zcross-crate-inline-threshold=always for some time, and has gotten testing in that form. However, this option is still unstable, to give an opportunity for wider testing in this form.

Some performance numbers, based on a crate with many dependencies having just one large dependency set to -Z hint-mostly-unused (using Cargo's profile-rustflags option):

A release build went from 4m07s to 2m04s.

A non-release build went from 2m26s to 1m28s.

[rustbot]

r? @GuillaumeGomez

rustbot has assigned @GuillaumeGomez.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[rustbot]

Some changes occurred to MIR optimizations

cc @rust-lang/wg-mir-opt

[GuillaumeGomez]

r? compiler

[workingjubilee]

This should be added as an unstable option first?

[workingjubilee]

@joshtriplett:

@workingjubilee This option has already existed in nightly as -Zcross-crate-inline-threshold=always for some time, and has gotten testing in that form.

The only difference being made between that option and this one is that this one respects #[inline(never)].

I see. I suppose that makes sense, though it brings these thoughts to mind:

• In general, T-compiler has a much lower threshold for unstable flags that are not intended for serious or permanent usage downstream. They're often added as debugging aids. I am not sure if this was intended for public usage when it was originally added.
• All inlining annotations are hints, and this is also noted as a hint, yet it changes the behavior of another inlining hint, and in that way deviates from its unstable variation.
• Notably, inline(never) is often relied on to some degree by programmers as working.
• This describes itself as a hint, but also is motivated on the basis that it will be very impactful, which suggests its behavior will be immediately relied on. The combination of relying-on-inlining-but-also-relying-on-not-inlining makes me wonder if it is definitely correct? There are a lot of weird nuances to our inlining rules.

As a result, I am curious if the rest of T-compiler believes changing the behavior with respect to inline(never) is trivial.

Perhaps this should land with a test that demonstrates that it respects #[inline(never)] correctly, now?

[workingjubilee]

( I'm also kinda curious if we should adjust how we handle cross-crate inlining by default, tbh. )

[lqd]

You may have missed it Jubilee, so hop on to https://rust-lang.zulipchat.com/#narrow/stream/233931-xxx/topic/Add.20.60-C.20hint-mostly-unused.60.20option.20compiler-team.23829 to ask your cool questions and comments :)

[fee1-dead]

r? compiler

[apiraino]

Discussed in T-compiler triage on Zulip.

MCP#829 still needs to be seconded and there seems to be still a few open design questions. Also, do we have some numbers about the real world impact (both positive and negative)?. Maybe it makes sense to nominate again once design and scope are clearer.

By the way @saethlin do you think you have some capacity to dedicate here?

@rustbot label -I-compiler-nominated

[joshtriplett]

Based on discussion about this at RustWeek, it sounded like this proposal had given the impression of wanting to rush stabilization, rather than being an unstable option to test and gather experience reports. Based on that discussion, I've reworked this PR and opened a new MCP to make it explicitly clear that this is an unstable option intended for a call for testing and for plumbing as a nightly Cargo option.

I've updated the implementation of this to be a -Z option, and added more documentation for it in the unstable book (including how to use Cargo to selectively enable it for specific crates).

I've also rebased it, re-tested it, and re-benchmarked it.