ACP: `ptr::is_aligned_for::<U>`

[mathisbot]

ACP: ptr::is_aligned_for::<U>

Summary

Introduce ptr::is_aligned_for<U>(self) -> bool on raw pointers (*const, *mut) and NonNull. This method checks whether the pointer is correctly aligned for a target type U, streamlining safe pointer casts without intermediate steps.

Alternatively (preferably?), introduce ptr::try_cast_aligned<U>(self) -> Option<Ptr<U>> on the same types. This method checks alignment and returns a casted pointer if it is correctly aligned.

Motivation

Currently, users that want to perform aligned read/write must cast before checking alignment:

#[repr(C)]
struct Complex {
    // ...
}

let ptr: *mut u8 = /* FFI pointer or any other provenance */ ;

assert!(ptr.cast::<Complex>().is_aligned(), "not aligned");
let complex_ptr = ptr.cast::<Complex>();

• Clippy lint: clippy::cast_ptr_alignment triggers even when alignment checks are valid.
• Readability: alignment intent is obscured by the needed cast.

Alternatively, users can use ptr::is_aligned_to, which is still unstable (see #96284) and less verbose.
Here, the problem of invalid alignments discussed in #96284 are not relevant as it would be provided by core::mem::align_of.

API

impl<T: ?Sized> *const T {
    pub fn is_aligned_for<U: Sized>(self) -> bool;
}

impl<T: ?Sized> *mut T { /* same */ }
impl<T: ?Sized> NonNull<T> { /* same */ }

Alternative: try_cast_aligned

As stated and suggested by @hanna-kruppe, it would be wise to combine alignment check and cast as follows:

impl<T: ?Sized> *const T {
    pub fn try_cast_aligned<U: Sized>(self) -> Option<*const U>;
}

impl<T: ?Sized> *mut T { /* same */ }
impl<T: ?Sized> NonNull<T> { /* same */ }

mirroring <[T]>::align_to but at a lower level.
This ensures the pointer is cast to the exact same type as the one used for alignment checks.

Rare cases (such as FFI) where the boolean value is needed, one could use ptr.try_cast_aligned::<SomeType>().is_some().
The implementation would be a combination of is_aligned_to and cast, so it would compile down to the exact same assembly as the hypothetical is_aligned_for.

The only downside of this solution is that it loses the verbosity of is_aligned_for in such cases.

References

• ptr::is_aligned's implementation

• Tracking issue (is_aligned_for): Tracking Issue for pointer_is_aligned_for rust#140980

• PR (is_aligned_for): Implement ptr::is_aligned_for and NonNull::is_aligned_for. rust#140982

• Tracking issue (try_cast_aligned): Tracking Issue for #![feature(pointer_try_cast_aligned)] rust#141221

• PR (try_cast_aligned): Implement ptr::try_cast_aligned and NonNull::try_cast_aligned. rust#141222

[hanna-kruppe]

Currently, checking that a pointer is properly aligned for a target type requires a cast prior to invoking ptr.is_aligned().
This can trigger the Clippy lint clippy::cast_ptr_alignment, which users must manually silence even though their check is valid.

The lint would have to learn to not warn about casts guarded by a is_aligned_for check. Probably doable, but as an outsider to clippy it’s not clear to me that this will be much easier than recognizing the cast + is_aligned pattern.

This ties to my other reservation about the proposal as written: while it allows checking alignment before casting, it doesn’t help with ensuring check + cast are always done together and agree on the type. An alternative would be something closer to <[T]>::align_to that combines alignment check and cast: try_cast_aligned(Ptr<T>) -> Option<Ptr<U>>.

[mathisbot]

An alternative would be something closer to <[T]>::align_to that combines alignment check and cast: try_cast_aligned(Ptr<T>) -> Option<Ptr<U>>.

I've updated the original post to include this idea.
As it comes from you, feel free to make the PR and everything else your own should the proposal be accepted. Otherwise, it would be a pleasure to do it myself 😊

[hanna-kruppe]

I have very limited time for open source contributions these days, and I don’t have a big need for this API myself, so I don’t intend to claim any of the work here for myself :)

[Amanieu]

We discussed this in the @rust-lang/libs-api meeting and accept the alternative proposed by @hanna-kruppe (try_cast_aligned). This seems strictly better than the original proposal.