Introduce a `PinSafePointer` trait that generalizes `PinCoerceUnsized` by Darksonn · Pull Request #156935 · rust-lang/rust

Darksonn · 2026-05-25T21:02:25Z

This PR renames PinCoerceUnsized to PinSafePointer and adds several new safety requirements about the implementations of various safe traits.

Closes: #152667
Closes: #147794

With this merged, the only remaining soundness issues with Pin are:

When subtyping can switch out trait impls, Pin::new’s check for Target: Unpin becomes insufficient #134407
The fact that CoercePointee may be implemented on Pin<LocalType> in downstream crates. (unstable only)

For your convenience here are the docs for the new trait:

`PinSafePointer`

Trait that indicates that this is a pointer that does not misbehave when combined with Pin.

Note that for backwards compatibility reasons, it is possible to create a Pin for pointer types P that do not implement this trait. However, this can only be done safely if ::Target implements Unpin, which means that pinning has no effect.

Safety

Types that implement this trait must not provide "malicious" implementations of any safe traits used by Pin.

The pointer must always reference the same object

Calls to deref/deref_mut on the same Pin instance must always refer to the same object. That is, the address returned by these methods must not change. This applies even if the pointer type is moved.

Furthermore, if the pointer type can participate in unsizing coercions or dynamic dispatch, then these coercions must also not change the underlying concrete type. Here, the concrete type of a trait object is the type that the vtable corresponds to. The concrete type of a slice is an array of the same element type and the length specified in the metadata. The concrete type of a sized type is the type itself.

As an example, after unsizing coercing a pinned pointer, deref_mut must not return a #[repr(transparent)] wrapper around the value it referenced before being unsized, even if the address is unchanged.

The pointer must not move its pointee

The deref_mut method and the pointer type's destructor are called with a &mut self receiver, but they must behave as-if it was a self: Pin<&mut Self> receiver. That is, they must not move out of the underlying value.

As an example, deref_mut must not invoke swap on the inner value.

Shared access to the pointer

If this pointer type uses &P references as evidence that this value is not pinned, then it must not treat the &self argument passed to Clone or the formatting traits (fmt::Debug, fmt::Display, fmt::Pointer) as such evidence.

As an example, given a Pin<Arc<T>> there is no way to obtain an &Arc<T> (note that Deref just gives a &T). Because of this, the Arc type can assume that an &Arc<T> value can only exist if the T is not pinned, which justifies the soundness of the Arc::get_mut method.

Cloning pinned pointers

When a Pin is cloned, the P pointer value returned by clone is passed to Pin::new_unchecked. The implementation of Clone must return a value such that this is sound.

For example, when a Pin<&T> is cloned, the resulting &T points at the same value. The value is known to be pinned since a Pin<&T> to it exists, so it is safe to wrap the &T returned by clone in Pin.

r? lcnr

Darksonn · 2026-05-25T21:03:13Z

+// safely as `Box::pin((*p).clone())`.
 #[unstable(feature = "pin_coerce_unsized_trait", issue = "150112")]
-unsafe impl<T: ?Sized, A: Allocator> PinCoerceUnsized for Box<T, A> {}
+unsafe impl<T: ?Sized, A: Allocator + 'static> PinSafePointer for Box<T, A> {}


I added A: 'static bounds to these impls since you generally cannot pin values in memory from a non-static allocator.

View changes since the review

Darksonn · 2026-05-25T21:04:21Z

+/// [`clone`]: Clone::clone
+/// [`Arc`]: ../../std/sync/struct.Arc.html "Arc"
+/// [`Arc::get_mut`]: ../../std/sync/struct.Arc.html#method.get_mut "Arc::get_mut"
+pub unsafe trait PinSafePointer: Deref + Sized {}


I added a Sized bound here due to #156920 (comment). This doesn't actually affect any use-cases since Pin already requires P: Sized, but seemed like a good idea nonetheless.

View changes since the review

RalfJung · 2026-05-27T17:02:19Z

+/// Calls to [`deref`]/[`deref_mut`] on the same `Pin<P>` instance must always
+/// refer to the same object. That is, the address returned by these methods
+/// must not change. This applies even if the pointer type is moved.


So this is still doing the thing where it talks about a DerefMut impl but DerefMut is not a supertrait of this trait. What are the valid ways in which an unsafe impl PinSafePointer can satisfy this requirement?

There's a DerefMut for the same set of types in the same crate: that's easy, we can just check the condition.

There's a negative DerefMut for the same set of types in the same crate: that's easy, no impl can exist so the condition is trivially satisfied.

Neither of these hold true. Now we... uh, look at the orphan rule and hope for the best? I am not sure that's a good idea, this is exactly what has bitten us in the past...

The same concern applies to the requirements on Clone, the formatting traits, and any others that I missed. (IMO the docs should call out more explicitly: If this type also implements Foo, then blah. If it also implements Bar, then blah. etc)

View changes since the review

I agree that it's best to avoid this kind of safety requirement, but I think we have no choice. Luckily we do not need to worry about dyn PinSafePointer.

This PR is adding comments to every impl of PinSafePointer explaining why the various trait implementations are compatible or cannot exist for the particular type in question. Please see the comments for various ways we can make these arguments.

Yeah in std we can do that because we have negative impls. But our users can't really do that... and the moment one wants to impl PinSafePointer for MyType<T> where MyType<T>: DerefMut for some but not all T, I don't see any way to make this work.

Negative impls are only required for fundamental types, so I'm not too concerned about that.

With regards to types where MyType<T>: DerefMut for some but not all T, we do in fact have one instance of exactly that. Please see #145608 for the trick to make that sound.

I have seen that PR and ran away screaming.^^

I really hope the reasoning is sound, but I do not have a coherent proof in my head -- it relies too much on orphan rule details.

RalfJung · 2026-05-27T17:15:33Z

+// with `Rc::get_mut`), this means that this type treats `&Rc<T>` as evidence
+// that the `T` is not pinned. The implementations of various traits are written
+// accordingly. Since this type is not fundamental, downstream crates cannot
+// provide malicious implementations of any of the traits relevant for `Pin`.


So this relies on something about the orphan rule, right? That makes me uneasy.^^
An explicit impl !DerefMut for Rc would be a lot better IMO.

View changes since the review

Yes, by the orphan rule downstream crates cannot implement DerefMut for Rc<_> under any scenario.

Those are the current orphan rules. How do we know they will never be relaxed?

The only promise the orphan rules are making is "there will never be more than one impl for the same trait + type". I don't think we should rely on any property that goes beyond this, and I don't see how the argument here follows from that property.

We can add a negative impl to simplify the reasoning for Rc, but I think there is no way out for the #145608 case unless someone comes up with an entirely different solution. It's simply unsound to add untrusted code to the coherence domain of core because it could implement DerefMut for Pin<LocalType> maliciously.

RalfJung · 2026-05-27T17:17:36Z

+/// If this pointer type uses `&P` references as evidence that this value is not
+/// pinned, then it must not treat the `&self` argument passed to [`Clone`] or
+/// the formatting traits ([`fmt::Debug`], [`fmt::Display`], [`fmt::Pointer`])
+/// as such evidence.
+///
+/// As an example, given a `Pin<Arc<T>>` there is no way to obtain an `&Arc<T>`
+/// (note that `Deref` just gives a `&T`). Because of this, the [`Arc`] type can
+/// assume that an `&Arc<T>` value can only exist if the `T` is not pinned,
+/// which justifies the soundness of the [`Arc::get_mut`] method.


I didn't realize get_mut becomes even more subtle when pinning gets involved. Impressive.

View changes since the review

Darksonn added T-lang Relevant to the language team T-libs-api Relevant to the library API team, which will review and decide on the PR/issue. A-pin Area: Pin labels May 25, 2026

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label May 25, 2026

rustbot assigned lcnr May 25, 2026

Darksonn commented May 25, 2026

View reviewed changes

Generalize PinCoerceUnsized into a new PinSafePointer trait

23a34ef

Darksonn force-pushed the pin-safe-pointer branch from 83c7d24 to 23a34ef Compare May 25, 2026 21:56

RalfJung reviewed May 27, 2026

View reviewed changes

Uh oh!

Conversation

Darksonn commented May 25, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PinSafePointer

Safety

The pointer must always reference the same object

The pointer must not move its pointee

Shared access to the pointer

Cloning pinned pointers

Uh oh!

Darksonn May 25, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Darksonn May 25, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RalfJung May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Darksonn May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RalfJung May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Darksonn May 27, 2026

Choose a reason for hiding this comment

Uh oh!

Darksonn May 27, 2026

Choose a reason for hiding this comment

Uh oh!

RalfJung May 27, 2026

Choose a reason for hiding this comment

Uh oh!

RalfJung May 27, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Darksonn May 27, 2026

Choose a reason for hiding this comment

Uh oh!

RalfJung May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Darksonn May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RalfJung May 27, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Darksonn commented May 25, 2026 •

edited by rustbot

Loading

`PinSafePointer`

Darksonn May 25, 2026 •

edited by rustbot

Loading

Darksonn May 25, 2026 •

edited by rustbot

Loading

RalfJung May 27, 2026 •

edited

Loading

Darksonn May 27, 2026 •

edited

Loading

RalfJung May 27, 2026 •

edited

Loading

RalfJung May 27, 2026 •

edited by rustbot

Loading

RalfJung May 27, 2026 •

edited

Loading

Darksonn May 27, 2026 •

edited

Loading

RalfJung May 27, 2026 •

edited by rustbot

Loading