RFC: Add an attribute for raising the alignment of various items #3806

Jules-Bertholet · 2025-05-01T22:19:24Z

Port C alignas to Rust.

text/3806-align-attr.md

hanna-kruppe · 2025-05-02T17:37:44Z

text/3806-align-attr.md

+The `align` attribute is a new inert, built-in attribute that can be applied to
+ADT fields, `static` items, function items, and local variable declarations. The
+attribute accepts a single required parameter, which must be a power-of-2
+integer literal from 1 up to 2<sup>29</sup>. (This is the same as
+`#[repr(align(…))]`.)


The 2^29 limit is way too high. The consistency with #[repr(align(..))] is a good default but alignments larger than a page or two have never worked properly in local variables (rust-lang/rust#70143) and in statics (rust-lang/rust#70022, rust-lang/rust#70144). While there are some use cases for larger alignments on types (if they're heap allocated) and an error on putting such a type in a local or static is ugly, for this new attribute we could just avoid the problem from the start.

For a struct field, both GCC and clang supported _Alignas(N) for N ≤ 2²⁸ (268435456).

The bug with local variables (rust-lang/rust#70143) seems to have been fixed everywhere except Windows, and just waiting on someone to fix it there as well in LLVM. (And even on Windows where the issue is not fixed, the only effect is to break the stack overflow protection, bringing it down to the same level as many Tier 2 targets.)

So the only remaining issue is with statics, where it looks like a target-specific max alignment might be necessary. Once implemented, that solution can be used to address align as well.

Overall, I don't think any of this is sufficient motivation to impose a stricter maximum on #[align].

Note that fixing the soundness issue for locals just means that putting a local with huge alignment in a stack frame is very likely to trigger the stack overflow check and abort the program. There is no use case for such massively over-aligned locals or statics, which is why those soundness issues been mostly theoretical problems and why the only progress toward fixing them over many years has been side effects of unrelated improvements (inline stack checks).

The only reason why the repr(align(..)) limit is so enormous is because it’s plausibly useful for heap allocations. Adding a second , lower limit for types put in statics and locals nowadays is somewhat tricky to design and drive to consensus (e.g., there’s theoretical backwards compatibility concerns) and not a priority for anyone, so who knows when it’ll happen. For #[align] we have the benefit of hindsight and could just mostly side-step the whole mess. I don’t see this as “needlessly restricting the new feature” but rather as “not pointlessly expanding upon an existing soundness issue for no reason”.

There is no use case for such massively over-aligned locals or statics

one use case I can think of is having a massive array that is faster because it's properly aligned so the OS can use huge pages (on x86_64, those require alignment $2^{19}$ or $2^{30}$), reducing TLB pressure. admittedly, that would only realistically be useful for statics or heap-allocated/mmap-ed memory.

To use huge pages for static data, you'd want to align the ELF segment containing the relevant sections (or equivalent in other formats), so the right tool there is a linker script or similar platform-specific mechanism. Over-aligning individual statics is a bad alternative:

It risks wasting a lot more (physical!) memory than expected if you end up with multiple statics in the program doing it and there's not enough other data to fill the padding required between them or they go in different sections.

If the linker/loader ignores the requested section alignment then that leads to UB if you used Rust-level #[align(N)]/#[repr(align(N))] and the code was optimized under that assumption.

While aligning statics appears easier and more portable than linker scripts, the reality is that platform/toolchain support for this is spotty anyway, so you really ought to carefully consider when and where to apply this trick.

In any case, I'm sure I'm technically wrong to claim that nobody could ever come up with a use case for massively over-aligned statics. But there's a reason why Linux and glibc have only started supporting it at all in the last few years, and other environments like musl-based Linux and Windows apparently doesn't support it at all (see discussion in aforementioned issues).

hanna-kruppe · 2025-05-02T17:40:31Z

text/3806-align-attr.md

+In Rust, a type’s size is always a multiple of its alignment. However, there are
+other languages that can interoperate with Rust, where this is not the case
+(WGSL, for example). It’s important for Rust to be able to represent such
+structures.


It's not clear to me how this would work while keeping Rust's "size is multiple of align" rule intact. I guess if it's about individual fields in a larger aggregate that maintains the rule in total? I don't know anything about WGSL so an example would be appreciated.

That’s exactly it. The WSGL example was taken from this comment on Internals: https://internals.rust-lang.org/t/pre-rfc-align-attribute/21004/20

Adding a worked example would indeed help readers of the RFC on this point.

Here is a concrete example of implementing Rust-WGSL compatibility using the #[align] attribute defined in this RFC. These structs have the same layout, and together demonstrate both inserting required padding (between foo and bar), and allowing a following field to be placed where a wrapper type would demand padding (baz immediately after bar):

// WGSL struct Example { // size = 32, alignment = 16 foo: vec3<f32>, // offset = 0, size = 12 bar: vec3<f32>, // offset = 16, size = 12 baz: f32, // offset = 28, size = 4 }

// Rust #[repr(linear)] // as defined in this RFC; repr(C) in current Rust #[derive(Debug, Copy, Clone, bytemuck::Pod, bytemuck::Zeroable)] pub(crate) struct Example { #[align(16)] foo: [f32; 3], // #[align] below causes 4 bytes of padding to be inserted here to satisfy it. #[align(16)] bar: [f32; 3], baz: f32, // If we used a wrapper for bar, this field would be at offset 32, wrongly }

It is often possible to order structure fields to fill gaps so that no inter-field padding is needed — such as if the fields in this example were declared in the order {foo, baz, bar} — and this is preferable when possible to avoid wasted memory, but the advantage of using #[align] in this scenario is that when used systematically, it can imitate WGSL's layout and thus will be correct even if the field ordering is not optimal.

(Please feel free to use any of the above text in the RFC.)

text/3806-align-attr.md

traviscross · 2025-05-08T03:04:32Z

We discussed this in the lang call today. We were feeling generally favorable about this, but all need to read it more closely.

Also, justify prohibition on fn params.

text/3806-align-attr.md

traviscross · 2025-05-16T16:55:28Z

text/3806-align-attr.md

+1. What should the syntax be for applying the `align` attribute to `ref`/`ref
+   mut` bindings?
+
+  - Option A: the attribute goes inside the `ref`/`ref mut`.
+
+```rust
+fn foo(x: &u8) {
+    let ref #[align(4)] _a = *x;
+}
+```
+
+  - Option B: the attribute goes outside the `ref`/`ref mut`.
+
+```rust
+fn foo(x: &u8) {
+    let #[align(4)] ref _a = *x;
+}
+```


Whatever we do, I'd expect it to be the same as for mut. So it's probably not worth deferring this question, as we need to handle it there.

As for where to put it, it seems like a bit of a coin toss. Anyone have a good argument for which way it should go?

I’m comfortable deferring it because I see no use-case for it, and I don’t want to hold up the RFC on something with no use case.

Sure, but still, I repeat my question, as we need to answer it for mut in any case, about whether there are good arguments for on which side of mut the attribute should appear.

The mut case does have actual use-cases, so I think we should handle the issue in the context of that, not this RFC.

Oh, wait, I think there may be a misunderstanding here. By “the same as for mut”, are you referring to combining mut with ref/ref mut?

No. This RFC specifies this is allowed (quoting from an example in the RFC):

let (a, #[align(4)] b, #[align(2)] mut c) = (4u8, 2u8, 1u8);

My question is whether there are good arguments about whether we should prefer that, or should instead prefer:

let (a, #[align(4)] b, mut #[align(2)] c) = (4u8, 2u8, 1u8);

The RFC should discuss any reasons we might want to prefer one over the other.

Separately, and secondarily, my feeling is that if we chose

let #[align(..)] mut a = ..;

then we would also choose:

let #[align(..)] ref a = ..;

And if we instead chose

let mut #[align(..)] a = ..;

then we would choose:

let ref #[align(..)] a = ..;

So my feeling is that in settling the question of how to syntactically combine #[align(..)] and mut, we are de facto settling the question of how to combine #[align(..)] with any other binding mode token.

I don’t agree that we would necessarily want to make the same choice in both cases. I actually think it depends on how mut and ref/ref mut should be combined.

If the combination looks like

let ref (mut x) = …; let ref mut (mut x) = …;

Then we should also do

let ref (#[align(…)] x) = …; let ref mut (#[align(…)] x) = …;

But if it looks like

let mut ref x = …; let mut ref mut x = …;

Then we should do

let #[align(…)] ref x = …; let #[align(…)] ref mut x = …;

In that event, and in your model, that would still leave us deciding between:

let ref (mut #[align(..)] x) = ..; // 1 // vs let ref (#[align(..)] mut x) = ..; // 2

And between:

let #[align(..)] mut ref x = ..; // 3 // vs let mut #[align(..)] ref x = ..; // 4

I would estimate that we'd comfortably favor 1, 3 over 2, 4.

There are also, of course, these possibilities:

let #[align(..)] ref (mut x) = ..; // 5 let mut ref #[align(..)] x = ..; // 6

If in this RFC we pick #[align(..) mut x, that would rule out for me option 1 if we later did ref (mut x) (and I wouldn't pick option 2 anyway). If we pick mut #[align(..)] x, that would rule out for me option 3 if we later did mut ref x (and I wouldn't pick option 4 anyway).

That is, even in this future possibility, I'm going to want to keep all of the binding mode tokens either to the left or to the right of the attribute.

I’ll elaborate in the RFC, but my preference is for 2 or 3.

I’ve added a section on this to the RFC.

text/3806-align-attr.md

traviscross · 2025-05-17T06:47:53Z

Having now had the chance to review this RFC thoroughly, I say that it's well written. Thanks to @Jules-Bertholet for that. It seems well motivated to me.

As mentioned above, I'd like for the document to speak more about the analysis of why one or another behavior is proper for async fn, and to speak to the arguments that would help us choose between let #[align(..)] mut x and let mut #[align(..)] x. I feel confident that whatever we do for placement here with respect to mut is also what we'd do with respect to other binding modes, so I'd prefer to just drop the restriction on other binding modes from this RFC. We could always later choose to partially stabilize.

If those things can perhaps be done, and the analysis with respect to async fn makes sense, then I plan to propose FCP merge on this RFC.

Jules-Bertholet · 2025-05-17T12:21:32Z

The arguments that would help us choose between let #[align(..)] mut x and let mut #[align(..)] x. I feel confident that whatever we do for placement here with respect to mut is also what we'd do with respect to other binding modes

This RFC proposes let #[align(…)] mut x, but I do not agree that we obviously want the same for ref and ref mut.

traviscross · 2025-05-17T12:29:31Z

This RFC proposes let #[align(…)] mut x, but I do not agree that we obviously want the same for ref and ref mut.

Then I'd appreciate if the RFC could discuss the reasons why we might want to make a different choice between these. It would surprise me a lot if we did, but I gather you must have a good argument in mind for this.

traviscross · 2025-05-17T12:33:36Z

cc @Nadrieril

text/3806-align-attr.md

RalfJung · 2025-05-18T18:55:51Z

text/3806-align-attr.md

+desirable, for optimal performance, to pack them into as few cache lines as
+possible. One way of doing this is to force the alignment of the value to be at
+least the size of the cache line, or perhaps the greatest common denominator of
+the value and cache line sizes.


I am very confused by this paragraph, and don't understand what it tries to say. By raising the alignment, the items will be further apart from each other (since each one must be properly aligned), and therefore it will take more cache lines, not fewer?

The idea is that you don't want a field to span across 2 cache lines if it could fit into just one. An easy way to achieve that is to make the field start at the start of a new cache line.

Aligning a field also means that a reference to it is aligned, which can improve performance in certain cases.

edit: i agree the text should explain this in more detail

I’ve reworded this paragraph.

Right, so you want to avoid false sharing, that makes sense.

The new text helps, thanks. The section title still says "Packing values into fewer cache lines" though, which doesn't seem to match the text.

It's not about false sharing -- if that was a problem, trailing padding until the next cache line boundary would be a plus. It's about possibly bringing fewer cache lines into the cache for common access patterns. This is a minor micro-optimization at best.

It's about possibly bringing fewer cache lines into the cache for common access patterns.

This is exactly it.

"Packing values into fewer cache lines"

As it pertains to the header, the ambiguity is the difference between packing the collection of all values into (maybe) fewer cache lines, or packing the bits of each value into (maybe) fewer cache lines.

The word "packing" tends to imply arranging many individual discrete things to fit in less space, and so is perhaps a misleading word for this when combined with "values".

I updated the paragraph again to clarify further.

RalfJung · 2025-05-18T18:56:57Z

text/3806-align-attr.md

+static LOOKUP_TABLE: CacheAligned<SomeLargeType> = CacheAligned(SomeLargeType {
+    data: todo!(),
+});


The example is confusing since SomeLargeType is declared as an array but then later we pretend it is a struct. I don't understand what this is trying to say.

Fixed, sorry. The contents of the type are immaterial, only the size matters

text/3806-align-attr.md

traviscross · 2025-05-19T16:24:43Z

In my view, this RFC is well motivated and has a lot of correct details. Thanks to @Jules-Bertholet for writing this up. I think we should do it with one adjustment.

Proposal: Accept this RFC as written, modulo that:

As far as this RFC goes, we allow #[align(..)] on bindings with all binding modes, and we specify the syntactic grammar as:

IdentifierPattern -> OuterAttribute* `ref`? `mut`? IDENTIFIER ( `@` PatternNoTopAlt )?

Semantically, for the moment, we would disallow attributes other than align.

If maybe we want to hold back on allowing align semantically with non-move binding modes, I propose we consider that at stabilization time rather than as a carve-out in this RFC.

The current text contains an argument about how this question should be tied in with a potential decision we might later make about syntax for reference bindings where the binding itself is mutable, but I don't buy it. We might or might not ever do that, and even if we did, it wouldn't change my own feeling that all the tokens that control the binding mode should appear together in the grammar. I find the grammar above just too compelling.

In terms of whether OuterAttribute* should appear before or after the binding mode tokens, I've tried some code with it both ways, and I agree it makes more sense at the start of the IdentifierPattern.

@rfcbot fcp merge

rfcbot · 2025-05-19T16:24:45Z

Team member @traviscross has proposed to merge this. The next step is review by the rest of the tagged team members:

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

cc @rust-lang/lang-advisors: FCP proposed for lang, please feel free to register concerns.
See this document for info about what commands tagged team members can give me.

Jules-Bertholet · 2025-05-19T16:46:34Z

Two, the text specifies disallowing align with _ (non-)bindings, let #[align(..)] _ = ... This feels more like a warning to me, so I propose that we allow this and consider warning on it.

Strongly disagree. I’ve updated the RFC

traviscross · 2025-05-19T17:16:40Z

Thanks, yes, that's right. Adjusted the proposal.

Jules-Bertholet force-pushed the align-attr branch from 75d8fc6 to f6f7686 Compare May 1, 2025 22:20

Add align_attr RFC

3a4f5ac

Jules-Bertholet force-pushed the align-attr branch from f6f7686 to 3a4f5ac Compare May 1, 2025 22:21

Jules-Bertholet mentioned this pull request May 1, 2025

Stabilize fn_align: #[repr(align(N))] on functions and -Zmin-function-alignment rust-lang/rust#140261

Open

This was referenced May 1, 2025

Rust unstable features needed for the kernel Rust-for-Linux/linux#2

Open

bindgen wanted features & bugfixes Rust-for-Linux/linux#353

Open

ehuss added the T-lang Relevant to the language team, which will review and decide on the RFC. label May 2, 2025

traviscross added I-lang-nominated Indicates that an issue has been nominated for prioritizing at the next lang team meeting. I-lang-radar Items that are on lang's radar and will need eventual work or consideration. labels May 2, 2025

kennytm reviewed May 2, 2025

View reviewed changes

text/3806-align-attr.md Show resolved Hide resolved

Jules-Bertholet force-pushed the align-attr branch from 800e69d to eca25f7 Compare May 2, 2025 14:05

Add more mixing packed and aligned to future possibilities

4badbc9

Jules-Bertholet force-pushed the align-attr branch from eca25f7 to 4badbc9 Compare May 2, 2025 14:07

hanna-kruppe reviewed May 2, 2025

View reviewed changes

kpreid reviewed May 2, 2025

View reviewed changes

text/3806-align-attr.md Outdated Show resolved Hide resolved

Avoid making commitments for interaction with extern static

2b647a8

Jules-Bertholet added 6 commits May 8, 2025 00:51

Expand comparison with C and C++

13cc4f2

Also, justify prohibition on fn params.

Minor clarifications

bbe09ee

Delete double spaces

81748b6

Thumb weirdness, expand discussion of repr

51b8069

Rephrase

855a766

Typo

1c7a402

folkertdev mentioned this pull request May 9, 2025

ACP: efficient runtime checking of multiple target features rust-lang/libs-team#585

Open

Jules-Bertholet mentioned this pull request May 14, 2025

Tracking Issue for #[repr(align(...))] on function items (fn_align) rust-lang/rust#82232

Open

3 tasks

traviscross added the P-lang-drag-2 Lang team prioritization drag level 2. label May 16, 2025

traviscross reviewed May 16, 2025

View reviewed changes

Jules-Bertholet added 2 commits May 16, 2025 14:41

Address async and closures

dee1e70

Elaborate on function parameters prohibition

4701919

traviscross reviewed May 17, 2025

View reviewed changes

text/3806-align-attr.md Outdated Show resolved Hide resolved

text/3806-align-attr.md Outdated Show resolved Hide resolved

text/3806-align-attr.md Show resolved Hide resolved

Jules-Bertholet added 3 commits May 17, 2025 10:52

Fix typo

59b1230

Justify async fn behavior

16f3bee

Elaborate on ref/ref mut

5229770

traviscross removed the I-lang-nominated Indicates that an issue has been nominated for prioritizing at the next lang team meeting. label May 18, 2025

traviscross reviewed May 18, 2025

View reviewed changes

text/3806-align-attr.md Show resolved Hide resolved

traviscross mentioned this pull request May 18, 2025

Design meeting: #[align(..)] rust-lang/lang-team#327

Open

Fix tpo

96350ee

Jules-Bertholet force-pushed the align-attr branch from e366c50 to 96350ee Compare May 18, 2025 18:29

RalfJung reviewed May 18, 2025

View reviewed changes

Jules-Bertholet added 5 commits May 18, 2025 15:09

Fix example

0c21fb3

Cache line clarifications

959a94c

Minor rephrase

75f615a

Fix typos

8b1fa67

Link to WGSL alignment rules

95f3972

traviscross reviewed May 19, 2025

View reviewed changes

text/3806-align-attr.md Show resolved Hide resolved

Function parameter prohibition is semantic

fefe945

rfcbot added proposed-final-comment-period Currently awaiting signoff of all team members in order to enter the final comment period. disposition-merge This RFC is in PFCP or FCP with a disposition to merge it. labels May 19, 2025

Justify not allowing attribute on _

a478717

Jules-Bertholet added 2 commits May 19, 2025 14:40

More cache clarifications

32b2a93

Rename a heading

f140b23

RFC: Add an attribute for raising the alignment of various items #3806

Are you sure you want to change the base?

RFC: Add an attribute for raising the alignment of various items #3806

Conversation

Jules-Bertholet commented May 1, 2025 • edited by rustbot Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

programmerjake May 8, 2025 • edited Loading

Choose a reason for hiding this comment

hanna-kruppe May 8, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kpreid May 18, 2025 • edited Loading

Choose a reason for hiding this comment

traviscross commented May 8, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

traviscross May 17, 2025 • edited Loading

Choose a reason for hiding this comment

Jules-Bertholet May 17, 2025 • edited Loading

Choose a reason for hiding this comment

Jules-Bertholet May 17, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

traviscross May 17, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

traviscross commented May 17, 2025 • edited Loading

Jules-Bertholet commented May 17, 2025

traviscross commented May 17, 2025 • edited Loading

traviscross commented May 17, 2025

Choose a reason for hiding this comment

folkertdev May 18, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

traviscross May 19, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Jules-Bertholet May 18, 2025 • edited Loading

Choose a reason for hiding this comment

traviscross commented May 19, 2025 • edited Loading

rfcbot commented May 19, 2025 • edited Loading

Jules-Bertholet commented May 19, 2025

traviscross commented May 19, 2025

Jules-Bertholet commented May 1, 2025 •

edited by rustbot

Loading

programmerjake May 8, 2025 •

edited

Loading

hanna-kruppe May 8, 2025 •

edited

Loading

kpreid May 18, 2025 •

edited

Loading

traviscross May 17, 2025 •

edited

Loading

Jules-Bertholet May 17, 2025 •

edited

Loading

Jules-Bertholet May 17, 2025 •

edited

Loading

traviscross May 17, 2025 •

edited

Loading

traviscross commented May 17, 2025 •

edited

Loading

traviscross commented May 17, 2025 •

edited

Loading

folkertdev May 18, 2025 •

edited

Loading

traviscross May 19, 2025 •

edited

Loading

Jules-Bertholet May 18, 2025 •

edited

Loading

traviscross commented May 19, 2025 •

edited

Loading

rfcbot commented May 19, 2025 •

edited

Loading