Skip to content

Commit 9173d09

Browse files
committed
Update cold to use the attribute template
1 parent 2334513 commit 9173d09

File tree

1 file changed

+37
-0
lines changed

1 file changed

+37
-0
lines changed

src/attributes/codegen.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,8 +71,42 @@ The `inline` attribute is ignored if the function is externally exported. This m
7171
r[attributes.codegen.cold]
7272
### The `cold` attribute
7373

74+
r[attributes.codegen.cold.intro]
7475
The *`cold` [attribute]* suggests that the attributed function is unlikely to be called.
7576

77+
> [!EXAMPLE]
78+
> ```rust
79+
> #[cold]
80+
> pub fn example() {}
81+
> ```
82+
83+
r[attributes.codegen.cold.syntax]
84+
The `cold` attribute uses the [MetaWord] syntax and thus does not take any inputs.
85+
86+
r[attributes.codegen.cold.allowed-positions]
87+
The `cold` attribute may only be used on:
88+
89+
- [Free functions][items.fn]
90+
- [Inherent associated functions][items.associated.fn]
91+
- [Trait impl functions][items.impl.trait]
92+
- [Trait definition functions][items.traits] with a body
93+
- [External block functions][items.extern.fn]
94+
- [Closures][expr.closure]
95+
96+
> [!NOTE]
97+
> `rustc` currently warns when `inline` is used in some other positions. This may become an error in the future.
98+
99+
<!-- TODO: rustc currently seems to allow cold on a trait function without a body, but it appears to be ignored. I think that may be a bug, and it should at least warn if not reject (like inline does). -->
100+
101+
r[attributes.codegen.cold.duplicates]
102+
Duplicate instances of the `cold` attribute are ignored.
103+
104+
> [!NOTE]
105+
> `rustc` currently warns on duplicate `cold` attributes.
106+
107+
r[attributes.codegen.cold.trait]
108+
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.
109+
76110
r[attributes.codegen.naked]
77111
## The `naked` attribute
78112
@@ -676,10 +710,12 @@ Using the `instruction_set` attribute has the following effects:
676710

677711
[`-C target-cpu`]: ../../rustc/codegen-options/index.html#target-cpu
678712
[`-C target-feature`]: ../../rustc/codegen-options/index.html#target-feature
713+
[`export_name`]: ../abi.md#the-export_name-attribute
679714
[`is_aarch64_feature_detected`]: ../../std/arch/macro.is_aarch64_feature_detected.html
680715
[`is_x86_feature_detected`]: ../../std/arch/macro.is_x86_feature_detected.html
681716
[`Location`]: core::panic::Location
682717
[`naked_asm!`]: ../inline-assembly.md
718+
[`no_mangle`]: ../abi.md#the-no_mangle-attribute
683719
[`target_feature` conditional compilation option]: ../conditional-compilation.md#target_feature
684720
[`unused_variables`]: ../../rustc/lints/listing/warn-by-default.html#unused-variables
685721
[attribute]: ../attributes.md
@@ -689,5 +725,6 @@ Using the `instruction_set` attribute has the following effects:
689725
[rust-abi]: ../items/external-blocks.md#abi
690726
[target architecture]: ../conditional-compilation.md#target_arch
691727
[trait]: ../items/traits.md
728+
[trait definition]: ../items/traits.md
692729
[undefined behavior]: ../behavior-considered-undefined.md
693730
[unsafe attribute]: ../attributes.md#r-attributes.safety

0 commit comments

Comments
 (0)