fix: add aliasing rules for Box

[DiuDiu777]

This is a new revised version for the PR 139857, sorry for the delayed reply. I've rewritten the sentence to closely mirror the wording from Vec::from_raw_parts, which clearly states the transfer of ownership and its consequences. This should make the aliasing requirements much clearer.

I opted not to include a note about mem::forget by default to keep the documentation focused on the primary contract, similar to Vec.

[rustbot]

r? @Mark-Simulacrum

rustbot has assigned @Mark-Simulacrum.
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

[Mark-Simulacrum]

As @RalfJung mentions in the other PR, this is perhaps too strict a condition with regards to forget (or not strict enough).

I'm also not sure if we've settled on this rule -- maybe this should instead link to https://doc.rust-lang.org/nightly/std/boxed/index.html#considerations-for-unsafe-code? That also notes the disclaimer that Box may be less restrictive than this makes it out to be.

[DiuDiu777]

Thanks for the feedback. In fact, the interaction with forget was a key point of uncertainty in my previous changes.

I agree with the method of adding the link to the "considerations for unsafe code" section. But the forget concerns do not seem to be clearly indicated in this link either. Should I also explicitly clarify the rules regarding mem::forget in this PR?

If I do this for Box, should I also update the documentation for APIs like Vec::from_raw_parts for consistency?

[RalfJung]

As written, this sentence would rule out code like this which is accepted by Miri:

let ptr = Box::into_raw(Box::new(0));
mem::forget(Box::from_raw(ptr));
drop(Box::from_raw(ptr));

Whether we want to allow such code or not is not something we have decided I think. The existing docs already rule out code like this which is accepted by Miri:

let mut a = 0;
mem::forget(Box::from_raw(&raw mut a));

That said, the corresponding Vec docs you mention are also quite restrictive here and don't allow anything like that. Vec isn't even subject to aliasing requirements. The docs there are written like this entirely because the destructor frees the memory.

[DiuDiu777]

@RalfJung Thanks for your detailed clarification! I can get your point.

As for the next step, can I add a note to the documentation mentioning that certain uses with mem::forget (like the examples you provided) are allowed? Or do you have a better suggestion for how to address this?

[SpriteOvO]

Hi, ping from triage team. This PR has been inactive for a while. Are there any updates on this?

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[DiuDiu777]

@rustbot ready

[Mark-Simulacrum]

View changes since the review

Strictly speaking, the ownership transfer is of the "memory", not the pointer (which is Copy).

Maybe we can just say "Note that the [considerations for unsafe code] apply to all Box<T> values"? That seems like it's both sufficient and avoids needing to get into much detail here.

[DiuDiu777]

Oh yeah, that's more straightforward. I'll update it~

[rustbot]

Reminder, once the PR becomes ready for a review, use @rustbot ready.

[DiuDiu777]

@rustbot ready

[Mark-Simulacrum]

@bors r+ rollup

[rust-bors]

📌 Commit c6befd8 has been approved by Mark-Simulacrum

It is now in the queue for this repository.