Tracking Issue for ptr::Alignment type

[scottmcm]

Feature gate: #![feature(ptr_alignment_type)]

This is a tracking issue for the ptr::Alignment type, and related methods, to represent values that are valid alignments in the rust abstract machine.

Public API

// core::ptr

#[derive(Copy, Clone, Eq, PartialEq)]
pub struct Alignment(…);

impl Debug for Alignment;
impl Ord for Alignment;
impl PartialOrd for Alignment;
impl Hash for Alignment;

impl Alignment {
    pub const MIN: Self;
    pub const fn of<T>() -> Self;
    pub const fn new(align: usize) -> Option<Self>;
    pub const unsafe fn new_unchecked(align: usize) -> Self;
    pub const fn as_usize(self) -> usize;
    pub const fn as_nonzero(self) -> NonZeroUsize;
    pub const fn log2(self) -> u32;
}

impl TryFrom<NonZeroUsize> for Alignment;
impl TryFrom<usize> for Alignment;
impl From<Alignment> for NonZeroUsize;
impl From<Alignment> for usize;

Steps / History

• ACP Add a specific type for pointer alignment libs-team#108
• Implementation: Add ptr::Alignment type #102072
• From<Alignment> for usize & NonZeroUsize #102862
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

• Is the mask method (from impl more traits for ptr::Alignment, add mask method #115249) correct? Should it be !(a - 1) or a - 1? Should it have a different name to distinguish it more from <*const _>::mask?

Footnotes

1. https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

[kupiakos]

I've been able to take advantage of an alignment newtype for performance in an embedded arena library and would find this useful to be stabilized. Are there any blockers for an FCP?

[m-ou-se]

We discussed this in the libs-api meeting just now. We think this type should be used in std APIs (e.g. methods of Layout) before stabilizing the type. Right now, this type doesn't seem to be used anywhere (publicly) in std, so we'd like to see a plan for usage of this type in std.

We also briefly talked about the error type in the TryFrom impls. It's not immediately clear if TryFromIntError is the right type. Perhaps it needs a new error type.

[clarfonthey]

As I'm trying to make a stable version of this API as a crate for my own use, I have a few questions about the current implementation:

1. Are alignments above isize::MAX actually allowed, given how most allocations are limited to isize::MAX instead of usize::MAX? This would complicate some of the code a bit (instead of is_power_of_two, you also need to check < isize::MAX), but seems like it would be desired if the goal is to represent actual alignments, and not just powers of two.
2. If the above is done, there should also be methods to convert to isize infallibly, and NonZeroIsize.
3. This type should implement Display, Binary, Octal, LowerHex, and UpperHex.
4. When I actually went to use this type, one case I felt was useful was a DoubledLen type, which includes both the powers of two and zero. The main reason for this was that for a particular hash table implementation, I wanted to assert with types that the length was a power of two, so that you can always mask out bits of an index instead of doing a modulus. Option<Alignment> does work for this, but I decided to go all-out here.
5. Another thing worth considering is methods for actually doing such masking: when actually checking if an address is aligned, you'll want to create a "mask" for that alignment, which effectively boils down to !(align - 1). Having a method to create this mask as a usize might be nice to have, and it also would be useful for the DoubledLen type I described.

[scottmcm]

1. Yes, because you can make isize::MAX+1-aligned ZST at the address ptr::invalid(isize::MIN as usize). That's probably not all that useful, but it's legal in the rust AM, as far as I know.
2. Agreed, having good ways to use this for things like masking (or aligning up/down) are important. I haven't gotten to making specifics for that; I'd encourage you to make some if you have something in mind.