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 15, 2024
1 parent 7caf35b commit 6ab68d8
Show file tree
Hide file tree
Showing 2 changed files with 20 additions and 12 deletions.
16 changes: 10 additions & 6 deletions library/core/src/ptr/const_ptr.rs
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,16 @@ impl<T: ?Sized> *const T {
///
/// ## 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.
/// When this function is used during const evaluation, this function will
/// panic if CTFE cannot determine whether the pointer is null or not. This
/// panic might or might not occur when `self` is a pointer that is offset
/// beyond the bounds of the memory it initially pointed to. Conversely,
/// this panic will never occur when `self` is in-bounds.
///
/// This inability to determine nullness occurs because there is no way for
/// CTFE to know the absolute position of that memory, so it might or might
/// not be possible to determine whether an offset out of bounds happens to
/// result in a null pointer.
///
/// # Examples
///
Expand Down
16 changes: 10 additions & 6 deletions library/core/src/ptr/mut_ptr.rs
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,16 @@ impl<T: ?Sized> *mut T {
///
/// ## 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.
/// When this function is used during const evaluation, this function will
/// panic if CTFE cannot determine whether the pointer is null or not. This
/// panic might or might not occur when `self` is a pointer that is offset
/// beyond the bounds of the memory it initially pointed to. Conversely,
/// this panic will never occur when `self` is in-bounds.
///
/// This inability to determine nullness occurs because there is no way for
/// CTFE to know the absolute position of that memory, so it might or might
/// not be possible to determine whether an offset out of bounds happens to
/// result in a null pointer.
///
/// # Examples
///
Expand Down

0 comments on commit 6ab68d8

Please sign in to comment.