Guarantee 8 bytes of alignment of RawWakerVTable

[orlp]

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]

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]

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

[BurntSushi]

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]

@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]

@rfcbot fcp merge libs-api

[rust-rfcbot]

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

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @the8472

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]

@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