Stabilize optimize attribute

[veluca93]

View all comments
FCP proposal and checkboxes

This commit stabilizes the #[optimize] attribute, which allows for more fine-grained control of optimization levels.

Stabilization report

Summary

Tracking issue: #54882
Reference PRs: rust-lang/reference#2278

cc @rust-lang/lang @rust-lang/lang-advisors @rust-lang/t-compiler

What is stabilized

// Instructs the optimization pipeline to prioritize smaller code size over speed.
#[optimize(size)]
pub fn binary_size_sensitive() {
    // ...
}

// Instructs the optimization pipeline to prioritize execution speed over code size.
#[optimize(speed)]
pub fn performance_critical() {
    // ...
}

// Disables optimizations entirely for this item.
#[optimize(none)]
pub fn debug_only() {
    // ...
}

What isn't stabilized

We might want to allow specifying a per-function optimization level (i.e. #[optimize(level = 3)]). To my understanding, backend support for this is not quite there yet (and this - or other - extensions have consequently not been implemented yet).

Applying the attribute on a module level is also not implemented yet.

Design

Reference

• Description of the new attribute: Stabilize #[optimize] attribute reference#2278

RFC history

• https://rust-lang.github.io/rfcs/2412-optimize-attr.html

Answers to unresolved question

• Should we also implement optimize(always)? optimize(level=x)?

Not yet.

• Should there be any way to specify what global optimization for speed level is used in conjunction with the optimization for speed option (e.g. -Copt-level=s3 could be equivalent to -Copt-level=3 and #[optimize(size)] on the crate item).

Not yet.

Post-RFC changes

The optimize(none) variant was added. The variants above were discussed here: #54882 (comment)

Key points

• #[optimize(none)] implies #[inline(never)] to be effective (#[optimize(none)] should imply #[inline(never)] #136329)
• As with all optimization-controlling flags, the effects on speed and binary size can be hard to predict: Tracking issue for RFC 2412, "The optimize attribute" #54882 (comment)
• Applying the attribute to incompatible items emits an error: Emit an error if #[optimize] is applied to an incompatible item #128458

Nightly uses

The standard library itself uses this attribute in a few places

Implementation

Major part

• Wiring it up to the llvm codegen backend:

  rust/compiler/rustc_codegen_llvm/src/attributes.rs

  Line 416 in c0bb140

  match codegen_fn_attrs.optimize {

• Catching usage on incompatible items: Emit an error if #[optimize] is applied to an incompatible item #128458
• Implementing optimize(none): Add #[optimize(none)] #128657 #[optimize(none)] implies #[inline(never)] #136358 (includes disabling MIR opts)

Coverage

• Basic tests: https://github.com/rust-lang/rust/blob/c0bb140a37c81cf59a0b40c21c9413059644e294/tests/ui/attributes/optimize.rs
• Testing the effect on compilation: https://github.com/rust-lang/rust/blob/c0bb140a37c81cf59a0b40c21c9413059644e294/tests/codegen-llvm/optimize-attr-1.rs

Tool changes

Trivial changes to rust-analyzer to support the new attribute as an inert attribute: rust-lang/rust-analyzer#22511

Type system, opsem

Breaks the AM?

As far as the AM is concerned, this attribute doesn't exist.

Acknowledgments

Most of the work was not done by me, I'm just writing the stabilization report :-)

@nagisa did the initial implementation, @clubby789 implemented optimize(none) and fixed the attribute being allowed in too many places.

Note

Concerns (0 active)

• are-we-happy-wiht-capability-and-scope-of-this-attribute resolved in this comment
• meaning-of-optimize-size resolved in this comment
• explicitly-decide-on-effect-on-nested-functions resolved in this comment

Managed by @rustbot—see help for details.

[rustbot]

rust-analyzer is developed in its own repository. If possible, consider making this change to rust-lang/rust-analyzer instead.

cc @rust-lang/rust-analyzer

[rustbot]

r? @JohnTitor

rustbot has assigned @JohnTitor.
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

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: compiler
• compiler expanded to 73 candidates
• Random selection from 17 candidates

[tgross35]

Given the interactions here, I expect this will need a lang+compiler FCP

@rustbot label +I-lang-nominated +I-compiler-nominated

See some recent discussion about this feature on Zulip #t-lang > status of #[optimize] attribute

[JohnTitor]

Marking as S-blocked given the current status.

[rustbot]

These commits modify tests/rustdoc-json.
rustdoc-json is a public (but unstable) interface.

Please ensure that if you've changed the output:

• It's intentional.
• The FORMAT_VERSION in src/librustdoc-json-types is bumped if necessary.

cc @aDotInTheVoid, @obi1kenobi

[obi1kenobi]

With my cargo-semver-checks hat on: do we expect this attribute to have SemVer implications?

For example, can applying or removing this attribute on an item influence the contexts in which that item may be used without compile errors or other changes that would be considered public-API-breaking?

[veluca93]

With my cargo-semver-checks hat on: do we expect this attribute to have SemVer implications?

For example, can applying or removing this attribute on an item influence the contexts in which that item may be used without compile errors or other changes that would be considered public-API-breaking?

I don't believe this is possible - the attribute should only influence how the compiler optimizes functions, and compiler optimizations should not have any visible effects.

[jieyouxu]

Discussion: hm, I wonder if this attribute deserves an entry in the rustc book (a bit like lint levels), because while sure there's the Reference PR, but this is more like a compiler knob?

View changes since the review

[theemathas]

See also #138272 for another example of optimize(none) functions not being treated as opaque for optimizations.

[nikic]

FYI LLVM 23 also has a noipa attribute. The combination of optnone + noipa should also disable all inter-procedural analysis and optimization. We may want to make optimize(none) to that.

[RalfJung]

#160524 resolves the implementation concerns here from my side -- on the MIR-opt side, optimize(none) now properly locally overwrites the opt level. (The one exception is the inliner pass which has some odd logic but cleaning that up is not a blocker for this.)

[veluca93]

I rebased the stabilization PR and updated the reference PR to include the "equivalent to -Copt-level=0" behaviour for optimize(none).
Is there anything else left to do?

[theemathas]

@TaKO8Ki, @jdonszelmann, @nikomatsakis, @scottmcm Your checkboxes are remaining at #157273 (comment)

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[theemathas]

@scottmcm @tmandry Could you resolve your concerns in the FCP?

[theemathas]

@veluca93 Does this PR have tests on: whether applying the attribute to a function affects closures defined within that function? And does the reference PR specify this?

[veluca93]

@veluca93 Does this PR have tests on: whether applying the attribute to a function affects closures defined within that function? And does the reference PR specify this?

Well, not this PR, it was merged in a previous one :-) The test is in tests/codegen-llvm/optimize-closures-inheritance.rs.

As for the reference PR: now it does ;)

[tmandry]

@rfcbot resolve should-apply-to-closures

[veluca93]

@scottmcm friendly ping :-)

[scottmcm]

@rfcbot resolve make-optimize-none-be-c-opt-level-0

[rust-rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[RalfJung]

Is this also covered by wherever the docs will go for #[optimize]?

If globally no optimisation is done, #[optimize] has no effect.

rust/compiler/rustc_codegen_ssa/src/base.rs

Line 1224 in 7d2cd0f

// If globally no optimisation is done, #[optimize] has no effect.

[veluca93]

Is this also covered by wherever the docs will go for #[optimize]?

If globally no optimisation is done, #[optimize] has no effect.

rust/compiler/rustc_codegen_ssa/src/base.rs

Line 1224 in 7d2cd0f

// If globally no optimisation is done, #[optimize] has no effect.

It was saying the wrong thing, now it should say the right thing :-) (rust-lang/reference#2278)

[rust-rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

[wesleywiser]

Thanks @veluca93 for pushing this over the finish line!

@bors r+ rollup

[rust-bors]

📌 Commit 5e2ccb2 has been approved by wesleywiser

It is now in the queue for this repository.

[rust-timer]

Note

This PR was benchmarked as part of triage of its containing rollup: triage URL.

Finished benchmarking commit (aab12df): comparison URL.

Overall result: ✅ improvements - no action needed

@rustbot label: -perf-regression

Instruction count

Our most reliable metric. Used to determine the overall result above. However, even this metric can be noisy.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	-	-	0
Improvements ✅ (primary)	-0.1%	[-0.3%, -0.1%]	4
Improvements ✅ (secondary)	-0.2%	[-0.5%, -0.1%]	15
All ❌✅ (primary)	-0.1%	[-0.3%, -0.1%]	4

Max RSS (memory usage)

This perf run didn't have relevant results for this metric.

Cycles

This perf run didn't have relevant results for this metric.

Binary size

This perf run didn't have relevant results for this metric.

Artifact size: 408.59 MiB -> 408.65 MiB (0.01%)

[JonathanBrouwer]

Probably noise, all PRs in the rollup seem to have similar results