Skip to content

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

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

DiuDiu777
Copy link
Contributor

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 like from_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:

The ownership of ptr is effectively transferred to the Vec<T> which may then deallocate, 
reallocate or change the contents of memory pointed to by the pointer at will. 
Ensure that nothing else uses the pointer after calling this function.

But Box's docs are currently missing this important warning.

@rustbot
Copy link
Collaborator

rustbot commented Apr 15, 2025

r? @jhpratt

rustbot has assigned @jhpratt.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

@rustbot rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Apr 15, 2025
@jhpratt
Copy link
Member

jhpratt commented Apr 19, 2025

I have no idea if this is correct…Ralf is probably the person that knows this best.

r? @RalfJung

@rustbot rustbot assigned RalfJung and unassigned jhpratt Apr 19, 2025
@@ -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.
Copy link
Member

@RalfJung RalfJung Apr 20, 2025

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants