pub unsafe trait PinSafePointer: Deref + Sized { }pin_coerce_unsized_trait #150112)Expand description
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<P> for pointer types P that do not implement this trait. However,
this can only be done safely if <P as Deref>::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<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.
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<P> 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.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".