Tracking Issue for pointer_is_aligned_to

[Gankra]

Feature gate: #![feature(pointer_is_aligned)]
Feature gate: #![feature(pointer_is_aligned_to)]

This is a tracking issue for ptr.is_aligned() and ptr.is_aligned_to(alignment).

Public API

impl *const T {
    // feature gate `pointer_is_aligned` was stabilized
    // pub fn is_aligned(self) -> bool where T: Sized;
    // feature gate `pointer_is_aligned_to`
    pub fn is_aligned_to(self, align: usize) -> bool;
}
// ... and the same for` *mut T`

impl <T: ?Sized> NonNull<T> {
    pub const fn is_aligned_to(self, align: usize) -> bool;
}

Steps / History

pointer_is_aligned:

• Implementation: Add convenience byte offset/check align functions to pointers #95643
• Final comment period (FCP): stabilize ptr.is_aligned, move ptr.is_aligned_to to a new feature gate #121948 (comment)
• Stabilization PR: stabilize ptr.is_aligned, move ptr.is_aligned_to to a new feature gate #121948

pointer_is_aligned_to:

• Implementation: Add convenience byte offset/check align functions to pointers #95643 and stabilize ptr.is_aligned, move ptr.is_aligned_to to a new feature gate #121948
• Move the NonNull method to this gate Stabilize non_null_convenience #124498
• Final comment period (FCP)
• Stabilization PR

Unresolved Questions

• Should is_aligned_to require a power of two or should it be more flexible? (currently panics)

[scottmcm]

For the unresolved question: another option might be to expose https://stdrs.dev/nightly/x86_64-unknown-linux-gnu/core/mem/valid_align/struct.ValidAlign.html and use it as the parameter type.

[WaffleLapkin]

I want to propose to stabilize these methods! (can someone open an fcp?)

Stabilization report

Implementation History

• Initially these methods were implemented in Add convenience byte offset/check align functions to pointers #95643
• Then the implementation was improved in Optimize pointer::is_aligned_to #100169
• The only unresolved question raised since then is whatever panicking in is_aligned_to on non-power of two align is acceptable.

API Summary

impl *const T {
    pub fn is_aligned(self) -> bool where T: Sized;
    pub fn is_aligned_to(self, align: usize) -> bool;
}

// ... and the same for` *mut T`

Experience Report

#100820 and #100823 refactored some std code into using these methods simplifying the code.

These methods were long requested (see for example #56304) and seem to be quite nice to use. They also may have slightly better codegen, compared to naive % align implementation.

[scottmcm]

I think the unresolved question needs an answer, not just a mention.

As I brought up earlier, I think it'd be really nice to have a type for valid alignments. The other two options are both unfortunate, IMHO: needing to assert!(align.is_power_of_two()) in something that would otherwise be a trivial bit of code, or just going 🤷 and returning garbage if the input isn't a power of two.

[WaffleLapkin]

So, our options for resolving the unresolved question:

1. Leave as-is, assert!(align.is_power_of_two())
   • Pros: notifies users of about invalid usages
   • Cons: in some cases adds an additional check/panic
2. Make behavior is case of !align.is_power_of_two() implementation defined (non-sensible result, debug_assert!, etc)
   • Pros: no performance penalty, ever
   • Cons: does not notify users about invalid usages
3. Introduce a type that holds always valid alignment
   • Pros: impossible to use incorrectly, such type can improve other APIs as well
   • Cons: bigger API surface, users need to move to new APIs (align_of2::<T>() -> Align?...), given an usize (e.g. from an external library) you need a trailing_zeros call to convert back

---

I'm leaning towards 2, but that's just me 🤷

[tyler274]

Could these methods be made const fns ?

[WaffleLapkin]

@tyler274 they can't, CTFE engine (compile time function execution) does not (necessarily) have a notion of "address" of a pointer. Since you can't take the address (e.g. it's UB to transmute::<*const (), usize>() in CTFE) you also can't check if it's divisible by something.

[scottmcm]

given an usize (e.g. from an external library) you need a trailing_zeros call to convert back

That's assuming it would be stored as log_2(align), but that's not necessary. In fact, the type that Layout uses internally today stores it as the power of two -- since that's convenient for things like the usual &(align-1) trick. So using a usize from an external library would be a "free" Alignment::new_unchecked call (if you can trust that other library).

EDIT: I opened an ACP to add an Alignment newtype to core: rust-lang/libs-team#108

[m-ou-se]

Question from the libs-api meeting: How often would one use is_aligned_to given that is_aligned exists? (Or maybe a is_aligned_for::<T>() might suffice for most cases?)

How often does one want to check a calculated alignment rather than a constant alignment? With e.g. .is_aligned_to(16), the check would be optimized away, making the usize argument fine. Using a separate Alignment type would only add extra verbosity.