Skip to content

Commit

Permalink
Rollup merge of rust-lang#128306 - WiktorPrzetacznik:WiktorPrzetaczni…
Browse files Browse the repository at this point in the history
…k-nonnull-alignoffset-update, r=Amanieu

Update NonNull::align_offset quarantees

This PR proposes to update [`NonNull::align_offset`](https://doc.rust-lang.org/stable/std/ptr/struct.NonNull.html#method.align_offset) guarantees, which should to be matched with [`ptr::align_offset`](https://doc.rust-lang.org/stable/std/primitive.pointer.html#method.align_offset-1)
(as `NonNull::align_offset` delegates to `ptr::align_offset`).

[PR rust-lang#121201](rust-lang#121201) updated only `ptr::align_offset` docs.
  • Loading branch information
matthiaskrgr authored Aug 8, 2024
2 parents d3a3939 + 3d7aa16 commit 3a9dd82
Showing 1 changed file with 10 additions and 3 deletions.
13 changes: 10 additions & 3 deletions library/core/src/ptr/non_null.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1169,16 +1169,23 @@ impl<T: ?Sized> NonNull<T> {
/// `align`.
///
/// If it is not possible to align the pointer, the implementation returns
/// `usize::MAX`. It is permissible for the implementation to *always*
/// return `usize::MAX`. Only your algorithm's performance can depend
/// on getting a usable offset here, not its correctness.
/// `usize::MAX`.
///
/// The offset is expressed in number of `T` elements, and not bytes.
///
/// There are no guarantees whatsoever that offsetting the pointer will not overflow or go
/// beyond the allocation that the pointer points into. It is up to the caller to ensure that
/// the returned offset is correct in all terms other than alignment.
///
/// When this is called during compile-time evaluation (which is unstable), the implementation
/// may return `usize::MAX` in cases where that can never happen at runtime. This is because the
/// actual alignment of pointers is not known yet during compile-time, so an offset with
/// guaranteed alignment can sometimes not be computed. For example, a buffer declared as `[u8;
/// N]` might be allocated at an odd or an even address, but at compile-time this is not yet
/// known, so the execution has to be correct for either choice. It is therefore impossible to
/// find an offset that is guaranteed to be 2-aligned. (This behavior is subject to change, as usual
/// for unstable APIs.)
///
/// # Panics
///
/// The function panics if `align` is not a power-of-two.
Expand Down

0 comments on commit 3a9dd82

Please sign in to comment.