Skip to content

Add "# Safety" and "# Examples" section in std::mem::uninitialized #151033

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
CieriA wants to merge 6 commits into
base: main
Choose a base branch
from
+33 −18
Open

Add "# Safety" and "# Examples" section in std::mem::uninitialized #151033

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
45d065c
library: Add Safety and Examples section in std::mem::uninitialized
CieriA Jan 12, 2026
2c7cad5
library: Add another example in `uninitialized` safety conditions
CieriA Jan 12, 2026
de12e31
library: use allow(deprecated) for uninitialized doctests
CieriA Jan 12, 2026
c7b6315
Reword safety of uninitialized for #151033 (comment)
CieriA Jan 21, 2026
47a2785
fix failed job
CieriA Jan 22, 2026
0a9127d
Merge branch 'main' into patch-6
CieriA Jan 22, 2026
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
15 changes: 15 additions & 0 deletions library/core/src/mem/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -705,9 +705,24 @@ pub const unsafe fn zeroed<T>() -> T {
/// Therefore, it is immediate undefined behavior to call this function on nearly all types,
/// including integer types and arrays of integer types, and even if the result is unused.
///
/// # Safety
///
/// This function is highly unsafe, as calling this function on nearly all types causes
/// undefined behavior. You should **always** prefer using [`MaybeUninit<T>`] instead.
///
/// If you absolutely must use this function, the following conditions must be upheld:
Copy link
Copy Markdown
Contributor

@tgross35 tgross35 Apr 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Change from "If you absolutely must use this function ..." to "On legacy codebases that use this function ..." or something similar, because nobody should have an absolute need to use it today :)

///
/// - `T` must be *valid* with any sequence of bytes of the appropriate length,
/// initialized or uninitialized.
Comment on lines +715 to +716
Copy link
Copy Markdown
Contributor

@tgross35 tgross35 Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should hint that non-ZST T effectively needs to be all MaybeUninit to account for the uninitialized requirement. Not sure about best wording but maybe something like:

"... That is, if T is not a ZST, it must be MaybeUninit or an ADT containing only MaybeUninit and padding."

Copy link
Copy Markdown
Contributor Author

@CieriA CieriA Jan 22, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, but wouldn't that suggest a correct usage of this function? I removed that part because it would suggest that using uninitialized() with ZSTs is acceptable (and you said that we should discourage usage of uninitialized() by not providing any example, that's why I kept the safety conditions a bit more "abstract"). What do you think?

Copy link
Copy Markdown
Contributor

@tgross35 tgross35 Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think mentioning the MaybeUninit requirement suggests anything more than what is already there, just makes it more obvious that this isn't sound even for POD types (since that's been a confusion point in the past). Not mentioning ZSTs seems reasonable though.

/// - `T` must be *[inhabited]*, i.e. possible to construct. This means that types
/// like zero-variant enums and [`!`] are unsound to construct with this function.
/// - You must use the value only in ways which do not violate any *safety*
/// invariants of the type.
///
/// [uninit]: MaybeUninit::uninit
/// [assume_init]: MaybeUninit::assume_init
/// [inv]: MaybeUninit#initialization-invariant
/// [inhabited]: https://doc.rust-lang.org/reference/glossary.html#inhabited
#[inline(always)]
#[must_use]
#[deprecated(since = "1.39.0", note = "use `mem::MaybeUninit` instead")]
Expand Down
36 changes: 18 additions & 18 deletions tests/ui/thir-print/offset_of.stdout
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,8 +67,8 @@ body:
}
)
else_block: None
hir_id: HirId(DefId(offset_of::concrete).10)
span: $DIR/offset_of.rs:37:5: 1440:57 (#0)
lint_level: Explicit(HirId(DefId(offset_of::concrete).10))
span: $DIR/offset_of.rs:37:5: 1455:57 (#0)
}
}
Stmt {
Expand Down Expand Up @@ -116,8 +116,8 @@ body:
}
)
else_block: None
hir_id: HirId(DefId(offset_of::concrete).20)
span: $DIR/offset_of.rs:38:5: 1440:57 (#0)
lint_level: Explicit(HirId(DefId(offset_of::concrete).20))
span: $DIR/offset_of.rs:38:5: 1455:57 (#0)
}
}
Stmt {
Expand Down Expand Up @@ -165,8 +165,8 @@ body:
}
)
else_block: None
hir_id: HirId(DefId(offset_of::concrete).30)
span: $DIR/offset_of.rs:39:5: 1440:57 (#0)
lint_level: Explicit(HirId(DefId(offset_of::concrete).30))
span: $DIR/offset_of.rs:39:5: 1455:57 (#0)
}
}
Stmt {
Expand Down Expand Up @@ -214,8 +214,8 @@ body:
}
)
else_block: None
hir_id: HirId(DefId(offset_of::concrete).40)
span: $DIR/offset_of.rs:40:5: 1440:57 (#0)
lint_level: Explicit(HirId(DefId(offset_of::concrete).40))
span: $DIR/offset_of.rs:40:5: 1455:57 (#0)
}
}
Stmt {
Expand Down Expand Up @@ -263,8 +263,8 @@ body:
}
)
else_block: None
hir_id: HirId(DefId(offset_of::concrete).50)
span: $DIR/offset_of.rs:41:5: 1440:57 (#0)
lint_level: Explicit(HirId(DefId(offset_of::concrete).50))
span: $DIR/offset_of.rs:41:5: 1455:57 (#0)
}
}
]
Expand Down Expand Up @@ -863,8 +863,8 @@ body:
}
)
else_block: None
hir_id: HirId(DefId(offset_of::generic).12)
span: $DIR/offset_of.rs:45:5: 1440:57 (#0)
lint_level: Explicit(HirId(DefId(offset_of::generic).12))
span: $DIR/offset_of.rs:45:5: 1455:57 (#0)
}
}
Stmt {
Expand Down Expand Up @@ -912,8 +912,8 @@ body:
}
)
else_block: None
hir_id: HirId(DefId(offset_of::generic).24)
span: $DIR/offset_of.rs:46:5: 1440:57 (#0)
lint_level: Explicit(HirId(DefId(offset_of::generic).24))
span: $DIR/offset_of.rs:46:5: 1455:57 (#0)
}
}
Stmt {
Expand Down Expand Up @@ -961,8 +961,8 @@ body:
}
)
else_block: None
hir_id: HirId(DefId(offset_of::generic).36)
span: $DIR/offset_of.rs:47:5: 1440:57 (#0)
lint_level: Explicit(HirId(DefId(offset_of::generic).36))
span: $DIR/offset_of.rs:47:5: 1455:57 (#0)
}
}
Stmt {
Expand Down Expand Up @@ -1010,8 +1010,8 @@ body:
}
)
else_block: None
hir_id: HirId(DefId(offset_of::generic).48)
span: $DIR/offset_of.rs:48:5: 1440:57 (#0)
lint_level: Explicit(HirId(DefId(offset_of::generic).48))
span: $DIR/offset_of.rs:48:5: 1455:57 (#0)
}
}
]
Expand Down
Loading