ACP: ptr::is_aligned_for::<U>

[mathisbot]

ACP: ptr::is_aligned_for::<U>

Summary

This proposal introduces a new method, ptr::is_aligned_for::<U>(self) -> bool, on raw pointers.
It streamlines alignment checks when casting pointers to a different type by eliminating the need for an intermediate, lint-triggering cast.
The new API mirrors ptr::is_aligned, using the alignment of the target type U.

Motivation

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.

Another solution is to call ptr::is_aligned_to with align_of::<U>(),
which is both less expressive and still unstable (see #96284) for matters of runtime checks.
This method deals with exactly the same goal as ptr::is_aligned, i.e. ensuring that the pointer alignment is valid (for aligned reads/writes) for aligned reads/writes after a cast.
As the alignment would be provided by align_of, the problem of invalid alignments discussed in #96284 are not relevant here.

Motivating examples

type Pixel = u32;

struct Screen {
    raw_buffer: &'static mut [Pixel]
}

impl Screen {
    pub fn new(raw_buffer: &'static mut [u8]) -> Self {
        let pixel_ptr = {
            let buffer_ptr = raw_buffer.as_mut_ptr();
            assert!(buffer_ptr.is_aligned_for::<Pixel>(), "Buffer is not aligned for Pixel");
            buffer_ptr.cast::<Pixel>()
        };

        // We can now safely create a slice from the pointer
        // as both the alignment and address are valid
        let pixel_slice = unsafe {
            core::slice::from_raw_parts_mut(
                pixel_ptr,
                raw_buffer.len() / size_of::<Pixel>()
            ) 
        };

        Self { raw_buffer: pixel_slice } 
    }
}

The above code can currently only be written as:

let pixel_ptr = {
    let buffer_ptr = raw_buffer.as_mut_ptr();
    assert!(buffer_ptr.cast::<Pixel>().is_aligned(), "Buffer is not aligned for Pixel");
    buffer_ptr.cast::<Pixel>()
};

which I think is less readable.

I am sure that there are examples dealing with FFI that would benefit from this as well (such as when dealing with C-void pointers).

API Design

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

impl<T: ?Sized> *mut T {
    #[must_use]
    #[inline]
    pub fn is_aligned_for<U: Sized>(self) -> bool;
}

impl<T: ?Sized> NonNull<T> {
    #[must_use]
    #[inline]
    pub fn is_aligned_for<U: Sized>(self) -> bool;
}

Alternative solutions

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

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

This ensures the pointer is cast to the exact same type as the one used for alignment checks.

Rare cases (such as FFI) where only the boolean value is needed 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 exactly the 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

• ptr::is_aligned_to tracking issue

• Tracking issue: Tracking Issue for pointer_is_aligned_for rust#140980

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

[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>>.