From 5da31583a4d38e9f4d267056013e9ad6115a6bc1 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 20 Jun 2025 17:56:03 -0700 Subject: [PATCH 1/7] Unwrap cold and inline --- src/attributes/codegen.md | 22 ++++++---------------- 1 file changed, 6 insertions(+), 16 deletions(-) diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index cf9837d9e..4f862313d 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -7,23 +7,16 @@ r[attributes.codegen.hint] ## Optimization hints r[attributes.codegen.hint.cold-inline] -The `cold` and `inline` [attributes] give suggestions to generate code in a -way that may be faster than what it would do without the hint. The attributes -are only hints, and may be ignored. +The `cold` and `inline` [attributes] give suggestions to generate code in a way that may be faster than what it would do without the hint. The attributes are only hints, and may be ignored. r[attributes.codegen.hint.usage] -Both attributes can be used on [functions]. When applied to a function in a -[trait], they apply only to that function when used as a default function for -a trait implementation and not to all trait implementations. The attributes -have no effect on a trait function without a body. +Both attributes can be used on [functions]. When applied to a function in a [trait], they apply only to that function when used as a default function for a trait implementation and not to all trait implementations. The attributes have no effect on a trait function without a body. r[attributes.codegen.inline] ### The `inline` attribute r[attributes.codegen.inline.intro] -The *`inline` [attribute]* suggests that a copy of the attributed function -should be placed in the caller, rather than generating code to call the -function where it is defined. +The *`inline` [attribute]* suggests that a copy of the attributed function should be placed in the caller, rather than generating code to call the function where it is defined. > [!NOTE] > The `rustc` compiler automatically inlines functions based on internal heuristics. Incorrectly inlining functions can make the program slower, so this attribute should be used with care. @@ -32,10 +25,8 @@ r[attributes.codegen.inline.modes] There are three ways to use the inline attribute: * `#[inline]` *suggests* performing an inline expansion. -* `#[inline(always)]` *suggests* that an inline expansion should always be - performed. -* `#[inline(never)]` *suggests* that an inline expansion should never be - performed. +* `#[inline(always)]` *suggests* that an inline expansion should always be performed. +* `#[inline(never)]` *suggests* that an inline expansion should never be performed. > [!NOTE] > `#[inline]` in every form is a hint, with no *requirements* on the language to place a copy of the attributed function in the caller. @@ -43,8 +34,7 @@ There are three ways to use the inline attribute: r[attributes.codegen.cold] ### The `cold` attribute -The *`cold` [attribute]* suggests that the attributed function is unlikely to -be called. +The *`cold` [attribute]* suggests that the attributed function is unlikely to be called. r[attributes.codegen.naked] ## The `naked` attribute From e8b19f2117820033bf89e024de5637df9272f57a Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 20 Jun 2025 18:42:50 -0700 Subject: [PATCH 2/7] Convert items.fn.attributes.builtin-attributes to a list --- src/items/functions.md | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/src/items/functions.md b/src/items/functions.md index e988077eb..264a07f90 100644 --- a/src/items/functions.md +++ b/src/items/functions.md @@ -417,11 +417,20 @@ fn documented() { > Except for lints, it is idiomatic to only use outer attributes on function items. r[items.fn.attributes.builtin-attributes] -The attributes that have meaning on a function are [`cfg`], [`cfg_attr`], [`deprecated`], -[`doc`], [`export_name`], [`link_section`], [`no_mangle`], [the lint check -attributes], [`must_use`], [the procedural macro attributes], [the testing -attributes], and [the optimization hint attributes]. Functions also accept -attributes macros. +The attributes that have meaning on a function are: + +- [`cfg_attr`] +- [`cfg`] +- [`deprecated`] +- [`doc`] +- [`export_name`] +- [`link_section`] +- [`must_use`] +- [`no_mangle`] +- [Lint check attributes] +- [Optimization hint attributes] +- [Procedural macro attributes] +- [Testing attributes] r[items.fn.param-attributes] ## Attributes on function parameters @@ -471,10 +480,10 @@ fn foo_oof(#[some_inert_attribute] arg: u8) { [attributes]: ../attributes.md [`cfg`]: ../conditional-compilation.md#the-cfg-attribute [`cfg_attr`]: ../conditional-compilation.md#the-cfg_attr-attribute -[the lint check attributes]: ../attributes/diagnostics.md#lint-check-attributes -[the procedural macro attributes]: ../procedural-macros.md -[the testing attributes]: ../attributes/testing.md -[the optimization hint attributes]: ../attributes/codegen.md#optimization-hints +[lint check attributes]: ../attributes/diagnostics.md#lint-check-attributes +[procedural macro attributes]: ../procedural-macros.md#attribute-macros +[testing attributes]: ../attributes/testing.md +[optimization hint attributes]: ../attributes/codegen.md#optimization-hints [`deprecated`]: ../attributes/diagnostics.md#the-deprecated-attribute [`doc`]: ../../rustdoc/the-doc-attribute.html [`must_use`]: ../attributes/diagnostics.md#the-must_use-attribute From 281f3a4b4f8220de57a179fa89e45eb51214dfd4 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 20 Jun 2025 18:48:11 -0700 Subject: [PATCH 3/7] Remove "optimization hints" section I didn't feel like this section was pulling its weight. It also wasn't entirely correct. --- src/attributes/codegen.md | 9 --------- src/items/functions.md | 6 ++++-- 2 files changed, 4 insertions(+), 11 deletions(-) diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 4f862313d..dfcd75fe3 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -3,15 +3,6 @@ r[attributes.codegen] The following [attributes] are used for controlling code generation. -r[attributes.codegen.hint] -## Optimization hints - -r[attributes.codegen.hint.cold-inline] -The `cold` and `inline` [attributes] give suggestions to generate code in a way that may be faster than what it would do without the hint. The attributes are only hints, and may be ignored. - -r[attributes.codegen.hint.usage] -Both attributes can be used on [functions]. When applied to a function in a [trait], they apply only to that function when used as a default function for a trait implementation and not to all trait implementations. The attributes have no effect on a trait function without a body. - r[attributes.codegen.inline] ### The `inline` attribute diff --git a/src/items/functions.md b/src/items/functions.md index 264a07f90..96bbc0b39 100644 --- a/src/items/functions.md +++ b/src/items/functions.md @@ -421,14 +421,15 @@ The attributes that have meaning on a function are: - [`cfg_attr`] - [`cfg`] +- [`cold`] - [`deprecated`] - [`doc`] - [`export_name`] +- [`inline`] - [`link_section`] - [`must_use`] - [`no_mangle`] - [Lint check attributes] -- [Optimization hint attributes] - [Procedural macro attributes] - [Testing attributes] @@ -483,7 +484,8 @@ fn foo_oof(#[some_inert_attribute] arg: u8) { [lint check attributes]: ../attributes/diagnostics.md#lint-check-attributes [procedural macro attributes]: ../procedural-macros.md#attribute-macros [testing attributes]: ../attributes/testing.md -[optimization hint attributes]: ../attributes/codegen.md#optimization-hints +[`cold`]: ../attributes/codegen.md#the-cold-attribute +[`inline`]: ../attributes/codegen.md#the-inline-attribute [`deprecated`]: ../attributes/diagnostics.md#the-deprecated-attribute [`doc`]: ../../rustdoc/the-doc-attribute.html [`must_use`]: ../attributes/diagnostics.md#the-must_use-attribute From e38127db37e529b6a40f99483f44e5b74ffcd87a Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 20 Jun 2025 18:48:42 -0700 Subject: [PATCH 4/7] Update inline to use the attribute template --- src/attributes/codegen.md | 40 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index dfcd75fe3..3d4aea3e2 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -9,9 +9,49 @@ r[attributes.codegen.inline] r[attributes.codegen.inline.intro] The *`inline` [attribute]* suggests that a copy of the attributed function should be placed in the caller, rather than generating code to call the function where it is defined. +> [!EXAMPLE] +> ```rust +> #[inline] +> pub fn example1() {} +> +> #[inline(always)] +> pub fn example2() {} +> +> #[inline(never)] +> pub fn example3() {} +> ``` + > [!NOTE] > The `rustc` compiler automatically inlines functions based on internal heuristics. Incorrectly inlining functions can make the program slower, so this attribute should be used with care. +r[attributes.codegen.inline.syntax] +The syntax for the `inline` attribute is: + +```grammar,attributes +@root InlineAttribute -> + `inline` `(` `always` `)` + | `inline` `(` `never` `)` + | `inline` +``` + +r[attributes.codegen.inline.allowed-positions] +The `inline` attribute may only be used on: + +- [Free functions][items.fn] +- [Inherent associated functions][items.associated.fn] +- [Trait impl functions][items.impl.trait] +- [Trait definition functions][items.traits] with a body +- [Closures][expr.closure] + +> [!NOTE] +> `rustc` currently warns when `inline` is used in some other positions. This may become an error in the future. + +r[attributes.codegen.inline.duplicates] +Only the first instance of `inline` on an item is honored. Subsequent `inline` attributes are ignored. + +> [!NOTE] +> `rustc` currently warns on duplicate `inline` attributes. This may become an error in the future. + r[attributes.codegen.inline.modes] There are three ways to use the inline attribute: From 2ccd26edfa495f5b19331080c9068d4221b5044f Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 20 Jun 2025 18:49:17 -0700 Subject: [PATCH 5/7] Add attributes.codegen.inline.trait This adds some wording that was removed from the "optimization hints" section. --- src/attributes/codegen.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 3d4aea3e2..00e8cee97 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -62,6 +62,9 @@ There are three ways to use the inline attribute: > [!NOTE] > `#[inline]` in every form is a hint, with no *requirements* on the language to place a copy of the attributed function in the caller. +r[attributes.codegen.inline.trait] +When `inline` is applied to a function in a [trait definition], it applies only to that function when used as a default function for a trait implementation and not to all trait implementations. + r[attributes.codegen.cold] ### The `cold` attribute From 2334513673292e37b928b8f368f9fef38ff000eb Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 20 Jun 2025 18:51:01 -0700 Subject: [PATCH 6/7] Add attributes.codegen.inline.externally-exported This rule did not seem to be covered elsewhere. I'm not 100% positive this is the best way to document this, but I think it is accurate. This is implemented in https://github.com/rust-lang/rust/blob/5526a2f47cd676ceeedc08cf71ae75ce2e9284ae/compiler/rustc_passes/src/check_attr.rs#L482-L497 --- src/attributes/codegen.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 00e8cee97..8e877247d 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -65,6 +65,9 @@ There are three ways to use the inline attribute: r[attributes.codegen.inline.trait] When `inline` is applied to a function in a [trait definition], it applies only to that function when used as a default function for a trait implementation and not to all trait implementations. +r[attributes.codegen.inline.externally-exported] +The `inline` attribute is ignored if the function is externally exported. This may happen with the [`no_mangle`] or [`export_name`] attribute. + r[attributes.codegen.cold] ### The `cold` attribute From 9173d09b1768f1790471c2e59176e6af7cd17325 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 20 Jun 2025 18:59:04 -0700 Subject: [PATCH 7/7] Update cold to use the attribute template --- src/attributes/codegen.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 8e877247d..3979a9561 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -71,8 +71,42 @@ The `inline` attribute is ignored if the function is externally exported. This m r[attributes.codegen.cold] ### The `cold` attribute +r[attributes.codegen.cold.intro] The *`cold` [attribute]* suggests that the attributed function is unlikely to be called. +> [!EXAMPLE] +> ```rust +> #[cold] +> pub fn example() {} +> ``` + +r[attributes.codegen.cold.syntax] +The `cold` attribute uses the [MetaWord] syntax and thus does not take any inputs. + +r[attributes.codegen.cold.allowed-positions] +The `cold` attribute may only be used on: + +- [Free functions][items.fn] +- [Inherent associated functions][items.associated.fn] +- [Trait impl functions][items.impl.trait] +- [Trait definition functions][items.traits] with a body +- [External block functions][items.extern.fn] +- [Closures][expr.closure] + +> [!NOTE] +> `rustc` currently warns when `inline` is used in some other positions. This may become an error in the future. + + + +r[attributes.codegen.cold.duplicates] +Duplicate instances of the `cold` attribute are ignored. + +> [!NOTE] +> `rustc` currently warns on duplicate `cold` attributes. + +r[attributes.codegen.cold.trait] +When `cold` is applied to a function in a [trait definition], it applies only to that function when used as a default function for a trait implementation and not to all trait implementations. + r[attributes.codegen.naked] ## The `naked` attribute @@ -676,10 +710,12 @@ Using the `instruction_set` attribute has the following effects: [`-C target-cpu`]: ../../rustc/codegen-options/index.html#target-cpu [`-C target-feature`]: ../../rustc/codegen-options/index.html#target-feature +[`export_name`]: ../abi.md#the-export_name-attribute [`is_aarch64_feature_detected`]: ../../std/arch/macro.is_aarch64_feature_detected.html [`is_x86_feature_detected`]: ../../std/arch/macro.is_x86_feature_detected.html [`Location`]: core::panic::Location [`naked_asm!`]: ../inline-assembly.md +[`no_mangle`]: ../abi.md#the-no_mangle-attribute [`target_feature` conditional compilation option]: ../conditional-compilation.md#target_feature [`unused_variables`]: ../../rustc/lints/listing/warn-by-default.html#unused-variables [attribute]: ../attributes.md @@ -689,5 +725,6 @@ Using the `instruction_set` attribute has the following effects: [rust-abi]: ../items/external-blocks.md#abi [target architecture]: ../conditional-compilation.md#target_arch [trait]: ../items/traits.md +[trait definition]: ../items/traits.md [undefined behavior]: ../behavior-considered-undefined.md [unsafe attribute]: ../attributes.md#r-attributes.safety