Skip to content

Commit

Permalink
Correctly document is_null CTFE behavior.
Browse files Browse the repository at this point in the history
The "panic in const if CTFE doesn't know the answer" behavior was discussed to be the desired behavior in rust-lang#74939, and is currently how the function actually behaves.

I intentionally wrote this documentation to allow for the possibility that a panic might not occur even if the pointer is out of bounds, because of rust-lang#133700 and other potential changes in the future.
  • Loading branch information
theemathas committed Dec 21, 2024
1 parent 7caf35b commit 9388917
Show file tree
Hide file tree
Showing 2 changed files with 22 additions and 16 deletions.
19 changes: 11 additions & 8 deletions library/core/src/ptr/const_ptr.rs
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,17 @@ impl<T: ?Sized> *const T {
/// Therefore, two pointers that are null may still not compare equal to
/// each other.
///
/// ## Behavior during const evaluation
///
/// When this function is used during const evaluation, it may return `false` for pointers
/// that turn out to be null at runtime. Specifically, when a pointer to some memory
/// is offset beyond its bounds in such a way that the resulting pointer is null,
/// the function will still return `false`. There is no way for CTFE to know
/// the absolute position of that memory, so we cannot tell if the pointer is
/// null or not.
/// # Panics during const evaluation
///
/// If this method is used during const evaluation, and `self` is a pointer
/// that is offset beyond the bounds of the memory it initially pointed to,
/// then there might not be enough information to determine whether the
/// pointer is null. This is because the absolute address in memory is not
/// known at compile time. If the nullness of the pointer cannot be
/// determined, this method will panic.
///
/// In-bounds pointers are never null, so the method will never panic for
/// such pointers.
///
/// # Examples
///
Expand Down
19 changes: 11 additions & 8 deletions library/core/src/ptr/mut_ptr.rs
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,17 @@ impl<T: ?Sized> *mut T {
/// Therefore, two pointers that are null may still not compare equal to
/// each other.
///
/// ## Behavior during const evaluation
///
/// When this function is used during const evaluation, it may return `false` for pointers
/// that turn out to be null at runtime. Specifically, when a pointer to some memory
/// is offset beyond its bounds in such a way that the resulting pointer is null,
/// the function will still return `false`. There is no way for CTFE to know
/// the absolute position of that memory, so we cannot tell if the pointer is
/// null or not.
/// # Panics during const evaluation
///
/// If this method is used during const evaluation, and `self` is a pointer
/// that is offset beyond the bounds of the memory it initially pointed to,
/// then there might not be enough information to determine whether the
/// pointer is null. This is because the absolute address in memory is not
/// known at compile time. If the nullness of the pointer cannot be
/// determined, this method will panic.
///
/// In-bounds pointers are never null, so the method will never panic for
/// such pointers.
///
/// # Examples
///
Expand Down

0 comments on commit 9388917

Please sign in to comment.