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.

[rust-log-analyzer]

The job tidy failed! Check out the build log: (web) (plain enhanced) (plain)

Click to see the possible cause of the failure (guessed by this bot)

fmt check
Diff in /checkout/library/alloc/src/boxed.rs:1268:
     /// The raw pointer must point to a block of memory allocated by the global allocator.
     ///
     /// The safety conditions are described in the [memory layout] section.
-    /// Additionally, transferring ownership of the pointer 
-    /// to the `Box<T>` introduces specific aliasing rules. Please see the 
+    /// Additionally, transferring ownership of the pointer
+    /// to the `Box<T>` introduces specific aliasing rules. Please see the
     /// [considerations for unsafe code] section for more details.
     ///
     /// # Examples
Diff in /checkout/library/alloc/src/boxed.rs:1321:
     /// The non-null pointer must point to a block of memory allocated by the global allocator.
     ///
     /// The safety conditions are described in the [memory layout] section.
-    /// Additionally, transferring ownership of the pointer 
-    /// to the `Box<T>` introduces specific aliasing rules. Please see the 
+    /// Additionally, transferring ownership of the pointer
+    /// to the `Box<T>` introduces specific aliasing rules. Please see the
     /// [considerations for unsafe code] section for more details.
     ///
     /// # Examples
Diff in /checkout/library/alloc/src/boxed.rs:1499:
     /// The raw pointer must point to a block of memory allocated by `alloc`.
     ///
     /// The safety conditions are described in the [memory layout] section.
-    /// Additionally, transferring ownership of the pointer 
-    /// to the `Box<T, A>` introduces specific aliasing rules. Please see the 
+    /// Additionally, transferring ownership of the pointer
+    /// to the `Box<T, A>` introduces specific aliasing rules. Please see the
     /// [considerations for unsafe code] section for more details.
     ///
     /// # Examples
Diff in /checkout/library/alloc/src/boxed.rs:1558:
     /// The non-null pointer must point to a block of memory allocated by `alloc`.
     ///
     /// The safety conditions are described in the [memory layout] section.
-    /// Additionally, transferring ownership of the pointer 
-    /// to the `Box<T, A>` introduces specific aliasing rules. Please see the 
+    /// Additionally, transferring ownership of the pointer
+    /// to the `Box<T, A>` introduces specific aliasing rules. Please see the
     /// [considerations for unsafe code] section for more details.
     ///
     /// # Examples
fmt: checked 6765 files
Bootstrap failed while executing `test src/tools/tidy tidyselftest --extra-checks=py,cpp,js,spellcheck`
Build completed unsuccessfully in 0:00:48