-
Notifications
You must be signed in to change notification settings - Fork 13.3k
Fix Box's doc for aliasing rules #139857
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: master
Are you sure you want to change the base?
Fix Box's doc for aliasing rules #139857
Conversation
I have no idea if this is correct…Ralf is probably the person that knows this best. r? @RalfJung |
@@ -1011,6 +1011,8 @@ impl<T: ?Sized> Box<T> { | |||
/// function is called twice on the same raw pointer. | |||
/// | |||
/// The raw pointer must point to a block of memory allocated by the global allocator. | |||
/// And you should enforce the aliasing rule by ensuring nothing else uses the | |||
/// raw pointer after calling this function. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please don't start a sentence with "and", that's not proper writing. Also, "enforce the aliasing rule" is unclear, at least it should say "enforce the aliasing rules", but even then it's still not clear what those rules are. Maybe just copy the wording from Vec::from_raw_parts
?
Also, it's not true that the raw pointer may never be used again. If you mem::forget
the Box
, you can use the raw pointer again. But the same is true for Vec
so maybe we deliberately don't talk about this in the docs? Cc @rust-lang/opsem
@rustbot author |
Reminder, once the PR becomes ready for a review, use |
We noticed there are four spots in
Box
's documentation where the safety notes are incomplete. According to Rust's stacked borrows rules, when APIs likefrom_raw
take ownership of a pointer's memory, that original pointer shouldn't be touched anymore. Other similar APIs make this clear, like Vec::from_raw_parts specifically says:But Box's docs are currently missing this important warning.