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.

Sign up for GitHub

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
Open

Fix Box's doc for aliasing rules #139857

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions library/alloc/src/boxed.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 •
edited
Loading

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

///
/// The safety conditions are described in the [memory layout] section.
///
Expand Down Expand Up @@ -1060,6 +1062,8 @@ impl<T: ?Sized> Box<T> {
/// function is called twice on the same `NonNull` pointer.
///
/// The non-null 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
/// non-null pointer after calling this function.
///
/// The safety conditions are described in the [memory layout] section.
///
Expand Down Expand Up @@ -1116,6 +1120,8 @@ impl<T: ?Sized, A: Allocator> Box<T, A> {
/// function is called twice on the same raw pointer.
///
/// The raw pointer must point to a block of memory allocated by `alloc`.
/// If the `alloc` is a global allocator, you should enforce the aliasing rule
/// by ensuring nothing else uses the raw pointer after calling this function.
///
/// # Examples
///
Expand Down Expand Up @@ -1169,6 +1175,8 @@ impl<T: ?Sized, A: Allocator> Box<T, A> {
/// function is called twice on the same raw pointer.
///
/// The non-null pointer must point to a block of memory allocated by `alloc`.
/// If the `alloc` is a global allocator, you should enforce the aliasing rule
/// by ensuring nothing else uses the non-null pointer after calling this function.
///
/// # Examples
///
Expand Down
Loading