You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The following [attributes] are used for controlling code generation.
5
5
6
-
r[attributes.codegen.hint]
7
-
## Optimization hints
8
-
9
-
r[attributes.codegen.hint.cold-inline]
10
-
The `cold` and `inline`[attributes] give suggestions to generate code in a
11
-
way that may be faster than what it would do without the hint. The attributes
12
-
are only hints, and may be ignored.
13
-
14
-
r[attributes.codegen.hint.usage]
15
-
Both attributes can be used on [functions]. When applied to a function in a
16
-
[trait], they apply only to that function when used as a default function for
17
-
a trait implementation and not to all trait implementations. The attributes
18
-
have no effect on a trait function without a body.
19
-
6
+
<!-- template:attributes -->
20
7
r[attributes.codegen.inline]
21
8
### The `inline` attribute
22
9
23
10
r[attributes.codegen.inline.intro]
24
-
The *`inline`[attribute]* suggests that a copy of the attributed function
25
-
should be placed in the caller, rather than generating code to call the
26
-
function where it is defined.
11
+
The *`inline`[attribute]* suggests whether a copy of the attributed function's code should be placed in the caller rather than generating a call to the function.
The `inline` attribute may only be applied to functions with [bodies] --- [closures], [async blocks], [free functions], [associated functions] in an [inherent impl] or [trait impl], and associated functions in a [trait definition] when those functions have a [default definition] .
27
40
28
41
> [!NOTE]
29
-
> 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.
42
+
> `rustc` ignores use in other positions but lints against it. This may become an error in the future.
43
+
44
+
> [!NOTE]
45
+
> Though the attribute can be applied to [closures] and [async blocks], the usefulness of this is limited as we do not yet support attributes on expressions.
46
+
>
47
+
> ```rust
48
+
> // We allow attributes on statements.
49
+
> #[inline] || (); // OK
50
+
> #[inline] async {}; // OK
51
+
> ```
52
+
>
53
+
> ```rust,compile_fail,E0658
54
+
> // We don't yet allow attributes on expressions.
55
+
> letf= #[inline] || (); // ERROR
56
+
> ```
57
+
58
+
r[attributes.codegen.inline.duplicates]
59
+
Onlythefirstuse of `inline` on a function has effect.
60
+
61
+
> [!NOTE]
62
+
> `rustc` lints against any use following the first.This may become an error in the future.
30
63
31
64
r[attributes.codegen.inline.modes]
32
-
There are three ways to use the inline attribute:
65
+
The `inline` attribute supports these modes:
33
66
34
-
*`#[inline]`*suggests* performing an inline expansion.
35
-
*`#[inline(always)]`*suggests* that an inline expansion should always be
36
-
performed.
37
-
*`#[inline(never)]`*suggests* that an inline expansion should never be
- `#[inline(always)]` *suggests* that inline expansion should always be performed.
69
+
- `#[inline(never)]` *suggests* that inline expansion should never be performed.
39
70
40
71
> [!NOTE]
41
-
> `#[inline]` in every form is a hint, with no *requirements* on the language to place a copy of the attributed function in the caller.
72
+
> In every form the attribute is a hint.The compiler may ignore it.
73
+
74
+
r[attributes.codegen.inline.trait]
75
+
When `inline` is applied to a function in a [trait], it applies only to the code of the [default definition].
42
76
77
+
r[attributes.codegen.inline.async]
78
+
When `inline` is applied to an [async function] or [async closure], it applies only to the code of the generated `poll` function.
79
+
80
+
> [!NOTE]
81
+
> For more details, see [Rust issue #129347](https://github.com/rust-lang/rust/issues/129347).
82
+
83
+
r[attributes.codegen.inline.externally-exported]
84
+
The `inline` attribute is ignored if the function is externally exported with [`no_mangle`] or [`export_name`].
85
+
86
+
<!-- template:attributes -->
43
87
r[attributes.codegen.cold]
44
88
### The `cold` attribute
45
89
46
-
The *`cold`[attribute]* suggests that the attributed function is unlikely to
47
-
be called.
90
+
r[attributes.codegen.cold.intro]
91
+
The*`cold` [attribute]* suggests that the attributed function is unlikely to be called which may help the compiler produce better code.
92
+
93
+
> [!EXAMPLE]
94
+
> ```rust
95
+
> #[cold]
96
+
> pubfn example() {}
97
+
> ```
98
+
99
+
r[attributes.codegen.cold.syntax]
100
+
The `cold` attribute uses the [MetaWord] syntax.
101
+
102
+
r[attributes.codegen.cold.allowed-positions]
103
+
The `cold` attribute may only be applied to functions with [bodies] --- [closures], [async blocks], [free functions], [associated functions] in an [inherent impl] or [traitimpl], and associated functions in a [trait definition] when those functions have a [default definition] .
104
+
105
+
> [!NOTE]
106
+
> `rustc` ignores usein other positions but lints against it.This may become an error in the future.
107
+
108
+
> [!NOTE]
109
+
> Though the attribute can be applied to [closures] and [async blocks], the usefulness of this is limited as we do not yet support attributes on expressions.
110
+
111
+
<!--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).-->
112
+
113
+
r[attributes.codegen.cold.duplicates]
114
+
Only the first use of `cold` on a function has effect.
115
+
116
+
> [!NOTE]
117
+
> `rustc` lints against any use following the first.This may become an error in the future.
118
+
119
+
r[attributes.codegen.cold.trait]
120
+
When `cold` is applied to a function in a [trait], it applies only to the code of the [default definition].
The `instruction_set` attribute uses the [MetaListPaths] syntax to specify a single path consisting of the architecture family name and instruction set name.
The `instruction_set` attribute may only be applied to functions, including [closures][expr.closure], [free functions][items.fn], and associated functions defined (i.e. with a body) in [inherent impls][items.associated.fn], [trait impls][items.impl.trait], and [trait definitions][items.traits].
731
+
The `instruction_set` attribute may only be applied to functions with [bodies] --- [closures], [async blocks], [free functions], [associated functions] in an [inherent impl] or [trait impl], and associated functions in a [trait definition] when those functions have a [default definition] .
659
732
660
733
> [!NOTE]
661
734
> `rustc` ignores use in other positions but lints against it. This may become an error in the future.
662
735
736
+
> [!NOTE]
737
+
> Though the attribute can be applied to [closures] and [async blocks], the usefulness of this is limited as we do not yet support attributes on expressions.
738
+
663
739
r[attributes.codegen.instruction_set.duplicates]
664
740
The `instruction_set` attribute may be used only once on a function.
665
741
@@ -684,18 +760,31 @@ If the address of the function is taken as a function pointer, the low bit of th
0 commit comments