From 59b5d8d771b5ccd9b7f4c4fc8e3f3e03897e4062 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/codegen.md | 45 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md
index 8b81758690..a0d71b0dae 100644
--- a/src/attributes/codegen.md
+++ b/src/attributes/codegen.md
@@ -220,6 +220,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(none)]
+> pub fn example2() {}
+>
+> #[optimize(speed)]
+> 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 disabling as many optimizations as possible.
+
+> [!NOTE]
+> In every form the attribute is a hint. The compiler may ignore it.
+
 r[attributes.codegen.target_feature]
 ## The `target_feature` attribute