Add Pin::static_ref, static_mut.

[m-ou-se]

This adds Pin::static_ref and Pin::static_mut, which convert a static reference to a pinned static reference.

Static references are effectively already pinned, as what they refer to has to live forever and can never be moved.

---

Context: I want to update the sys and sys_common mutexes/rwlocks/condvars to use Pin<&self> in their functions, instead of only warning in the unsafety comments that they may not be moved. That should make them a little bit less dangerous to use. Putting such an object in a static (e.g. through sys_common::StaticMutex) fulfills the requirements about never moving it, but right now there's no safe way to get a Pin<&T> to a static. This solves that.

[rust-highfive]

r? @shepmaster

(rust_highfive has picked a reviewer for you, use r? to override)

[m-ou-se]

@rustbot modify labels: +T-libs

[withoutboats]

Separate from my comments on #77801, I think this method is somewhat interesting. I can think of a use case of using it to pin a PinCell for example.

I think the mutable equivalent is even more interesting, though, because other than PinCell there is not much use for Pin<&T>. So I would add these unstably as a pair of methods: static_ref and static_mut:

impl<T: ?Sized> Pin<&'static T> {
    pub fn static_ref(r: &'static T) -> Self { ... }
}

impl<T: ?Sized> Pin<&'static mut T> {
    pub fn static_mut(r: &'static mut T) -> Self { ... }
}

[shepmaster]

r? @withoutboats

[withoutboats]

@rfcbot fcp merge

This PR adds two constructors for pinned references: from &'static T and &'static mut T; these constructors are sound because you can never move or invalidate something to which you have a 'static reference.

[rfcbot]

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

• @Amanieu
• @BurntSushi
• @KodrAus
• @dtolnay
• @sfackler
• @withoutboats

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.

[withoutboats]

Another API we could consider in the future (but I'm not sure its useful enough) is adding leak to Pin<Box<T>> etc:

impl<T: ?Sized> Pin<Box<T>> {
    fn leak(this: Pin<Box<T>>) -> Pin<&'static mut T> { /* .. */ }
}

// equivalent expressions:
let x = Pin::leak(Box::pin(expr));
let x = Pin::static_mut(Box::leak(Box::new(expr)));

[dtolnay]

I see 3/6 checkboxes and this PR is just adding unstable methods so I think we can land without waiting for an FCP.

[dtolnay]

@bors r+

[bors]

📌 Commit df95dce has been approved by dtolnay

[Mark-Simulacrum]

This was backported into 1.48 (approved by me) in #79075 as a dependency of #77801.