Guarantee 8 bytes of alignment of RawWakerVTable by orlp · Pull Request #158186 · rust-lang/rust

orlp · 2026-06-20T19:10:02Z

This is similar to an earlier PR I made for Thread::into_raw: #143859.

When using AtomicPtr for synchronization it's incredibly useful when you've got a couple bits you can stuff metadata in. By guaranteeing that RawWakerVTable is aligned to 8 bytes everyone can use the bottom 3 bits to signal other things, such as a critical section, etc. In particular, this can be used to portably implement an AtomicWaker which is always two pointers in size, no more.

On almost all platforms the align is already 8 bytes, and on other platforms it might cause an infinitesimal increase in size. This guarantee is thus very useful and costs us essentially nothing.

r? libs-api

Like last time since this adds a guarantee this probably needs a FCP.

BurntSushi · 2026-06-20T19:24:53Z

I like this. Having unused bits in a pointer is really useful.

In particular, this can be used to portably implement an AtomicWaker which is always two pointers in size, no more.

Would it be reasonable to add a basic example of this? It would be great for docs to not just provide the guarantee but give a real example where it's useful.

orlp · 2026-06-20T19:32:53Z

@BurntSushi I'm afraid the example would be far too long and too subtle for the docs on this.

BurntSushi · 2026-06-20T19:53:39Z

Maybe we can shorten it so that it just hows how to (correctly) use those lower bits in the pointer to store something? It can be a pretty subtle thing to get correct in my experience. I know I've toiled over it. It would be a real gem to have something like that in the docs precisely where a guarantee affording such chicanery is written.

orlp · 2026-06-20T23:01:52Z

@BurntSushi I mean feel free to take a look: https://gist.github.com/orlp/de53ae21e357f92f705052d8760e9517.

Ultimately I don't think the RawWakerVTable docs is the right place to teach people about what pointer bit stuffing is or how it works.

BurntSushi · 2026-06-20T23:27:12Z

@rfcbot fcp merge libs-api

rust-rfcbot · 2026-06-20T23:27:14Z

@BurntSushi 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!

See this document for info about what commands tagged team members can give me.

BurntSushi · 2026-06-20T23:32:46Z

@orlp Thanks! I actually don't think that example is too big for std's docs personally. It seems rather useful and could be an awesome addition to the docs. It "just" needs to be broken down into pieces and explained with some exposition. (I think this could be hard to do.)

As for pointer tagging more broadly, probably the provenance APIs are the place for that. And at least there is an unstable API that has a lightweight example of it: https://doc.rust-lang.org/nightly/std/primitive.pointer.html#method.mask

nia-e · 2026-08-11T15:19:16Z

cc @adamgreig & @therealprof on behalf of wg-embedded - is this change likely to impact you negatively? otherwise we'd be happy to accept this PR ^^

jnkel · 2026-08-25T17:41:13Z

I expect the impact on embedded to be negligible. Waker vtables are const statics; an application will not have more than a handful of them, and increasing the alignment shouldn't make much of a difference as there are plenty of things the compiler/linker can use to fill the space (especially on a 32-bit platform where you have tons of 4-byte variables).

I built a moderately-sized Embassy project on the latest main:

Section Headers:
  [Nr] Name              Type            Addr     Off    Size   ES Flg Lk Inf Al
  [ 0]                   NULL            00000000 000000 000000 00      0   0  0
  [ 1] .cy_m0p_image     PROGBITS        10000000 000154 0018d0 00  AR  0   0  1
  [ 2] .resources        PROGBITS        10100000 001a24 06ec2d 00   A  0   0  1
  [ 3] .vector_table     PROGBITS        10002000 070654 0002e0 00   A  0   0  4
  [ 4] .text             PROGBITS        100022e0 070934 01d2e0 00  AX  0   0  4
  [ 5] .rodata           PROGBITS        1001f5c0 08dc14 0065e0 00 AMS  0   0  4
  [ 6] .data             PROGBITS        08000800 0941f4 000020 00  WA  0   0  4
  [ 7] .gnu.sgstubs      PROGBITS        10025bc0 094220 000000 08   A  0   0 32
  [ 8] .bss              NOBITS          08000820 094220 0248b8 00 WAR  0   0  8
  [ 9] .uninit           NOBITS          080250d8 094220 000000 00  WA  0   0  4
  [10] .defmt            PROGBITS        00000000 094220 00006a 00   R  0   0  1
  [11] .debug_loc        PROGBITS        00000000 09428a 0bd2ab 00      0   0  1
  [12] .debug_abbrev     PROGBITS        00000000 151535 001432 00      0   0  1
  [13] .debug_info       PROGBITS        00000000 152967 149afc 00      0   0  1
  [14] .debug_aranges    PROGBITS        00000000 29c463 0042f8 00      0   0  1
  [15] .debug_ranges     PROGBITS        00000000 2a075b 02ec08 00      0   0  1
  [16] .debug_str        PROGBITS        00000000 2cf363 16940c 01  MS  0   0  1
  [17] .comment          PROGBITS        00000000 43876f 000087 01  MS  0   0  1
  [18] .ARM.attributes   ARM_ATTRIBUTES  00000000 4387f6 000032 00      0   0  1
  [19] .debug_frame      PROGBITS        00000000 438828 00a6bc 00      0   0  4
  [20] .debug_line       PROGBITS        00000000 442ee4 03fae3 00      0   0  1
  [21] .symtab           SYMTAB          00000000 4829c8 008720 10     23 1828  4
  [22] .shstrtab         STRTAB          00000000 48b0e8 0000f6 00      0   0  1
  [23] .strtab           STRTAB          00000000 48b1de 01a8d4 00      0   0  1

Latest main + this patch:

Section Headers:
  [Nr] Name              Type            Addr     Off    Size   ES Flg Lk Inf Al
  [ 0]                   NULL            00000000 000000 000000 00      0   0  0
  [ 1] .cy_m0p_image     PROGBITS        10000000 000154 0018d0 00  AR  0   0  1
  [ 2] .resources        PROGBITS        10100000 001a24 06ec2d 00   A  0   0  1
  [ 3] .vector_table     PROGBITS        10002000 070654 0002e0 00   A  0   0  4
  [ 4] .text             PROGBITS        100022e0 070934 01d2e0 00  AX  0   0  4
  [ 5] .rodata           PROGBITS        1001f5c0 08dc18 0065e4 00 AMS  0   0  8
  [ 6] .data             PROGBITS        08000800 0941fc 000020 00  WA  0   0  4
  [ 7] .gnu.sgstubs      PROGBITS        10025be0 094220 000000 08   A  0   0 32
  [ 8] .bss              NOBITS          08000820 094220 0248b8 00 WAR  0   0  8
  [ 9] .uninit           NOBITS          080250d8 094220 000000 00  WA  0   0  4
  [10] .defmt            PROGBITS        00000000 094220 00006a 00   R  0   0  1
  [11] .debug_loc        PROGBITS        00000000 09428a 0bd2ab 00      0   0  1
  [12] .debug_abbrev     PROGBITS        00000000 151535 001432 00      0   0  1
  [13] .debug_info       PROGBITS        00000000 152967 149afc 00      0   0  1
  [14] .debug_aranges    PROGBITS        00000000 29c463 0042f8 00      0   0  1
  [15] .debug_ranges     PROGBITS        00000000 2a075b 02ec08 00      0   0  1
  [16] .debug_str        PROGBITS        00000000 2cf363 16940c 01  MS  0   0  1
  [17] .comment          PROGBITS        00000000 43876f 000087 01  MS  0   0  1
  [18] .ARM.attributes   ARM_ATTRIBUTES  00000000 4387f6 000032 00      0   0  1
  [19] .debug_frame      PROGBITS        00000000 438828 00a6bc 00      0   0  4
  [20] .debug_line       PROGBITS        00000000 442ee4 03fae3 00      0   0  1
  [21] .symtab           SYMTAB          00000000 4829c8 008720 10     23 1828  4
  [22] .shstrtab         STRTAB          00000000 48b0e8 0000f6 00      0   0  1
  [23] .strtab           STRTAB          00000000 48b1de 01a8d4 00      0   0  1

The code size increased by four bytes (the .rodata section increased in size from 0065e0 to 0065e4).

rustbot · 2026-08-28T13:58:06Z

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

rust-rfcbot · 2026-09-01T15:07:33Z

🔔 This is now entering its final comment period, as per the review above. 🔔

adamgreig · 2026-09-01T18:59:12Z

No objections from wg-embedded, we don't expect a meaningful impact.

rust-rfcbot · 2026-09-11T15:08:01Z

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

clarfonthey · 2026-09-16T19:29:52Z

@bors r+ rollup

rust-bors · 2026-09-16T19:29:55Z

📌 Commit fd4d2e6 has been approved by clarfonthey

It is now in the queue for this repository.

…fonthey Guarantee 8 bytes of alignment of RawWakerVTable This is similar to an earlier PR I made for `Thread::into_raw`: rust-lang#143859. When using `AtomicPtr` for synchronization it's incredibly useful when you've got a couple bits you can stuff metadata in. By guaranteeing that `RawWakerVTable` is aligned to 8 bytes everyone can use the bottom 3 bits to signal other things, such as a critical section, etc. In particular, this can be used to portably implement an `AtomicWaker` which is always two pointers in size, no more. On almost all platforms the align is already 8 bytes, and on other platforms it might cause an infinitesimal increase in size. This guarantee is thus very useful and costs us essentially nothing. --- r? libs-api Like last time since this adds a guarantee this probably needs a FCP.

…uwer Rollup of 8 pull requests Successful merges: - #162796 (libtest: do not early exit from test runners) - #162844 (Add loan reachability traces to polonius MIR dumps) - #158186 (Guarantee 8 bytes of alignment of RawWakerVTable) - #160108 (Stabilize `windows_process_extensions_main_thread_handle`) - #161305 (Use the entire type of a dropped local to compute variance (edge direction) for Polonius alpha) - #161838 (tests: accept LLVM 24 optimization in this test) - #162825 (core: Add examples for `debug_closure_helpers`) - #162856 (Stabilize CommandExt::show_window)

…fonthey Guarantee 8 bytes of alignment of RawWakerVTable This is similar to an earlier PR I made for `Thread::into_raw`: rust-lang#143859. When using `AtomicPtr` for synchronization it's incredibly useful when you've got a couple bits you can stuff metadata in. By guaranteeing that `RawWakerVTable` is aligned to 8 bytes everyone can use the bottom 3 bits to signal other things, such as a critical section, etc. In particular, this can be used to portably implement an `AtomicWaker` which is always two pointers in size, no more. On almost all platforms the align is already 8 bytes, and on other platforms it might cause an infinitesimal increase in size. This guarantee is thus very useful and costs us essentially nothing. --- r? libs-api Like last time since this adds a guarantee this probably needs a FCP.

Rollup of 12 pull requests Successful merges: - #161596 (coretests: Add more pattern tests.) - #162796 (libtest: do not early exit from test runners) - #162844 (Add loan reachability traces to polonius MIR dumps) - #158186 (Guarantee 8 bytes of alignment of RawWakerVTable) - #160108 (Stabilize `windows_process_extensions_main_thread_handle`) - #160212 (traits: Fix rigid alias liveness matching) - #160544 (Stabilize `feature(trim_prefix_suffix)` (`{str, [T], Path}::trim_prefix` and `{str, [T]}::trim_suffix`)) - #161305 (Use the entire type of a dropped local to compute variance (edge direction) for Polonius alpha) - #161838 (tests: accept LLVM 24 optimization in this test) - #162805 (Add `must_use` lint to `ExitCode`) - #162825 (core: Add examples for `debug_closure_helpers`) - #162856 (Stabilize CommandExt::show_window)

Zalathar · 2026-09-17T02:11:01Z

This change (predictably) fails semver checks in CI: #162877 (comment)

I assume it needs some special directive to skip those checks for a deliberate “breaking” change, though I don’t know offhand what that is. IIRC there’s some relevant discussion on Zulip somewhere.

@bors r-

rust-bors · 2026-09-17T02:11:09Z

This pull request was unapproved.

This PR was contained in the following rollups:

Rollup of 8 pull requests #162869 was unapproved
Rollup of 12 pull requests #162877 was unapproved

View changes since this unapproval

Zalathar · 2026-09-17T02:17:03Z

https://rust-lang.zulipchat.com/#narrow/channel/219381-t-libs/topic/Breakages.20detected.20by.20cargo-semver-checks/with/622258268

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Jun 20, 2026

rustbot assigned BurntSushi Jun 20, 2026

rust-rfcbot added proposed-final-comment-period Proposed to merge/close by relevant subteam, see T-<team> label. Will enter FCP once signed off. disposition-merge This issue / PR is in PFCP or FCP with a disposition to merge it. labels Jun 20, 2026

joshtriplett reviewed Aug 11, 2026

View reviewed changes

Comment thread library/core/src/task/wake.rs Outdated

This comment has been minimized.

Sign in to view

Guarantee 8 bytes of alignment of RawWakerVTable

fd4d2e6

orlp force-pushed the rawwaker-vtable-align branch from 904ecef to fd4d2e6 Compare August 28, 2026 13:58

rust-rfcbot added final-comment-period In the final comment period and will be merged soon unless new substantive objections are raised. and removed proposed-final-comment-period Proposed to merge/close by relevant subteam, see T-<team> label. Will enter FCP once signed off. labels Sep 1, 2026

rustbot mentioned this pull request Sep 11, 2026

Tracking issue for release notes of #158186: Guarantee 8 bytes of alignment of RawWakerVTable #162645

Open

rust-bors Bot added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 16, 2026

JonathanBrouwer mentioned this pull request Sep 16, 2026

Rollup of 9 pull requests #162866

Closed

JonathanBrouwer mentioned this pull request Sep 16, 2026

Rollup of 8 pull requests #162869

Open

Zalathar mentioned this pull request Sep 17, 2026

Rollup of 12 pull requests #162877

Closed

rust-bors Bot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Sep 17, 2026

Uh oh!

Uh oh!

Conversation

orlp commented Jun 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BurntSushi commented Jun 20, 2026

Uh oh!

orlp commented Jun 20, 2026

Uh oh!

BurntSushi commented Jun 20, 2026

Uh oh!

orlp commented Jun 20, 2026

Uh oh!

BurntSushi commented Jun 20, 2026

Uh oh!

rust-rfcbot commented Jun 20, 2026 • edited by joshtriplett Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BurntSushi commented Jun 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

nia-e commented Aug 11, 2026

Uh oh!

jnkel commented Aug 25, 2026

Uh oh!

This comment has been minimized.

rustbot commented Aug 28, 2026

Uh oh!

rust-rfcbot commented Sep 1, 2026

Uh oh!

adamgreig commented Sep 1, 2026

Uh oh!

rust-rfcbot commented Sep 11, 2026

Uh oh!

clarfonthey commented Sep 16, 2026

Uh oh!

rust-bors Bot commented Sep 16, 2026

Uh oh!

Zalathar commented Sep 17, 2026

Uh oh!

rust-bors Bot commented Sep 17, 2026

Uh oh!

Zalathar commented Sep 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

10 participants

orlp commented Jun 20, 2026 •

edited

Loading

rust-rfcbot commented Jun 20, 2026 •

edited by joshtriplett

Loading

BurntSushi commented Jun 20, 2026 •

edited

Loading