Improve the documentation around layout gurantees given by Box#155597
Improve the documentation around layout gurantees given by Box#155597weiznich wants to merge 1 commit intorust-lang:mainfrom
Box#155597Conversation
rustbot
added
S-waiting-on-review
|
rustbot has assigned @Mark-Simulacrum. Use Why was this reviewer chosen?The reviewer was selected based on:
|
| //! convert between `Box<A>` and `Box<B>` using unsafe code if its sound to do the same conversion | ||
| //! between `A` and `B`. | ||
| //! | ||
| //! For zero-sized values, the `Box` pointer has to be non-null and sufficiently aligned. The |
There was a problem hiding this comment.
The existing text has two paragraphs covering the two cases "non-zero-sized" and "zero-sized". Please don't break that structure by adding an entirely unrelated paragraph in the middle.
There was a problem hiding this comment.
I put it a bit further down. If that's still a bad location please suggest a better one.
| //! obtained from [`Box::<T>::into_raw`] may be deallocated using the [`Global`] allocator with | ||
| //! [`Layout::for_value(&*value)`]. | ||
| //! | ||
| //! It can be assumed that the layout of `Box<A>` is compatible to the layout of `Box<B>` if |
There was a problem hiding this comment.
I'm a bit concerned that we have never defined what "compatible layout" actually means. I don't think we are using it in existing docs, are we?
There was a problem hiding this comment.
What about going with "The layout is the same for Box<A> and Box<B> if it's the same for A and B instead?
There was a problem hiding this comment.
That uses a different word but doesn't fix the problem that we haven't actually defined the terms you are using here.
Fundamentally the problem is that we have basically no documentation of the sort you want to add, and adding the first pieces of such documentation needs a lot of infrastructure (like term definitions) to be established. Cc @traviscross @ehuss
Also it occurs to me that it seems odd to make this guarantee for Box but not for raw pointers or references.
There was a problem hiding this comment.
This is using the wording out of the nomicon:
When transmuting between different compound types, you have to make sure they are laid out the same way! If layouts differ, the wrong fields are going to get filled with the wrong data, which will make you unhappy and can also be Undefined Behavior (see above).
So how do you know if the layouts are the same? For repr(C) types and repr(transparent) types, layout is precisely defined. But for your run-of-the-mill repr(Rust), it is not. Even different instances of the same generic type can have wildly different layout. Vec and Vec might have their fields in the same order, or they might not. The details of what exactly is and is not guaranteed for data layout are still being worked out over at the UCG WG.
For me that reads like there is some existing usage of "the same layout" defined there, so I'm rather surprised to hear that "same layout" is not defined yet.
This change extends the memory layout section in the documentation of `Box` to explicitly state that it is sound to convert between `Box<A>` and `Box<B>` as long as it is sound to convert between `A` and `B` directly. See https://rust-lang.zulipchat.com/#narrow/channel/136281-t-opsem/topic/Is.20transmuting.20between.20.60Box.3CA.3E.60.20and.20.60Box.3CB.3E.60.20UB.3F/with/585350243 for the relevant discussion.
weiznich
force-pushed
the
docs/better_box_layout_docs
branch
from
b17e07b to
ad7e61c
Compare
4 participants
This change extends the memory layout section in the documentation of
Boxto explicitly state that it is sound to convert betweenBox<A>andBox<B>as long as it is sound to convert betweenAandBdirectly.See
https://rust-lang.zulipchat.com/#narrow/channel/136281-t-opsem/topic/Is.20transmuting.20between.20.60Box.3CA.3E.60.20and.20.60Box.3CB.3E.60.20UB.3F/with/585350243 for the relevant discussion.