From e9f9d990e0f0325d2fdde9e1736230e68ed90edf Mon Sep 17 00:00:00 2001
From: Luca Versari <veluca93@gmail.com>
Date: Mon, 1 Jun 2026 21:34:14 +0200
Subject: [PATCH] Stabilize #[optimize] attribute

---
 src/attributes.md         |  2 ++
 src/attributes/codegen.md | 45 +++++++++++++++++++++++++++++++++++++++
 src/items/functions.md    |  2 ++
 3 files changed, 49 insertions(+)

diff --git a/src/attributes.md b/src/attributes.md
index 7b405a143c..45fbbc534f 100644
--- a/src/attributes.md
+++ b/src/attributes.md
@@ -255,6 +255,7 @@ The following is an index of all built-in attributes.
   - [`cold`] --- Hint that a function is unlikely to be called.
   - [`naked`] --- Prevent the compiler from emitting a function prologue and epilogue.
   - [`no_builtins`] --- Disables use of certain built-in functions.
+  - [`optimize`] --- Controls the level of optimization to be applied to the function.
   - [`target_feature`] --- Configure platform-specific code generation.
   - [`track_caller`] --- Pass the parent call location to `std::panic::Location::caller()`.
   - [`instruction_set`] --- Specify the instruction set used to generate a function's code.
@@ -328,6 +329,7 @@ The following is an index of all built-in attributes.
 [`no_mangle`]: abi.md#the-no_mangle-attribute
 [`no_std`]: names/preludes.md#the-no_std-attribute
 [`non_exhaustive`]: attributes/type_system.md#the-non_exhaustive-attribute
+[`optimize`]: attributes/codegen.md#the-optimize-attribute
 [`panic_handler`]: panic.md#the-panic_handler-attribute
 [`path`]: items/modules.md#the-path-attribute
 [`proc_macro_attribute`]: procedural-macros.md#the-proc_macro_attribute-attribute
diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md
index b1a79f3edc..ac4b308d2d 100644
--- a/src/attributes/codegen.md
+++ b/src/attributes/codegen.md
@@ -235,6 +235,51 @@ Only the first use of the `no_builtins` attribute has effect.
 > [!NOTE]
 > `rustc` lints against any use following the first.
 
+<!-- template:attributes -->
+r[attributes.codegen.optimize]
+## The `optimize` attribute
+
+r[attributes.codegen.optimize.intro]
+The *`optimize` [attribute]* suggests whether a function, inherent method, trait method, or closure should be optimized for size or speed.
+
+> [!EXAMPLE]
+> ```rust
+> #[optimize(size)]
+> pub fn example1() {}
+>
+> #[optimize(speed)]
+> pub fn example2() {}
+>
+> #[optimize(none)]
+> pub fn example3() {}
+> ```
+
+r[attributes.codegen.optimize.syntax]
+The syntax for the `optimize` attribute is:
+
+```grammar,attributes
+@root OptimizeAttribute ->
+      `optimize` `(` `size` `)`
+    | `optimize` `(` `speed` `)`
+    | `optimize` `(` `none` `)`
+```
+
+r[attributes.codegen.optimize.allowed-positions]
+The `optimize` attribute may only be applied to [closures], [async blocks], [free functions], [associated functions] in an [inherent impl] or [trait impl], and associated functions in a [trait definition].
+
+r[attributes.codegen.optimize.duplicates]
+Applying multiple `optimize` attributes to the same function is an error.
+
+r[attributes.codegen.optimize.modes]
+The `optimize` attribute supports these modes:
+
+- `#[optimize(size)]` suggests prioritizing minimizing code size, potentially at the cost of execution performance.
+- `#[optimize(speed)]` suggests prioritizing execution performance, potentially at the cost of code size.
+- `#[optimize(none)]` suggests not optimizing the function, with similar effects to applying -Copt-level=0 locally.
+
+> [!NOTE]
+> In every form the attribute is a hint. The compiler may ignore it.
+
 r[attributes.codegen.target_feature]
 ## The `target_feature` attribute
 
diff --git a/src/items/functions.md b/src/items/functions.md
index 25ae723a20..db10195793 100644
--- a/src/items/functions.md
+++ b/src/items/functions.md
@@ -707,6 +707,7 @@ The attributes that have meaning on a function are:
 - [`link_section`]
 - [`must_use`]
 - [`no_mangle`]
+- [`optimize`]
 - [Lint check attributes]
 - [Procedural macro attributes]
 - [Testing attributes]
@@ -764,6 +765,7 @@ fn foo_oof(#[some_inert_attribute] arg: u8) {
 [`export_name`]: ../abi.md#the-export_name-attribute
 [`link_section`]: ../abi.md#the-link_section-attribute
 [`no_mangle`]: ../abi.md#the-no_mangle-attribute
+[`optimize`]: ../attributes/codegen.md#the-optimize-attribute
 [built-in attributes]: ../attributes.md#built-in-attributes-index
 [trait item]: traits.md
 [method]: associated-items.md#methods