Re: `Pin` from `&mut` refs

[dhm]

@zrk

the current “imprecise” documentation does not really express a lot of guarantees on “pinned objects", and so cannot really be a source of unsoundness, can it?

We have:

@From https://doc.rust-lang.org/beta/std/pin/index.html

In order to prevent objects from moving, they must be pinned by wrapping a pointer to the data in the Pin type. Doing this prohibits moving the value behind the pointer. For example, Pin<Box<T>> functions much like a regular Box<T> , but doesn't allow moving T .

For me the guarantees from an API-consumer point of view are pretty well expressed (i.e., if someone somehow gets a Pin<impl Deref<Target = T>>, they can then rely on T's address never changing) ; the documentation problem is "for the other side of the API", i.e. for the person that goes unsafe and attempts to construct such a Pin object (e.g. the wrong but dangerously intuitive Pin<&'a mut T> : From<&'a mut T>).

That is "the worst kind" of guarantees, i.e. one that will "inevitably" lead to unsoundness (take, for instance, the damage caused by an "innocent-looking" function such as ::std::mem::zeroed<T : Sized> () -> T)