[GrigorenkoPV]

View all comments

Tracking issue: #102070

Stabilized API

All used to be gated under ptr_alignment_type, now stabilized under alignment_type:

// in `core::mem`

#[derive(Copy, Clone, PartialEq, Eq)]
pub struct Alignment { ... }

impl Alignment {
    pub const MIN: Self;
    pub const fn of<T>() -> Self;
    pub const fn of_val<T: ?Sized>(val: &T) -> Self;
    pub const fn of_val_raw<T: ?Sized>(val: *const 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_usize(self) -> NonZero<usize>;
}

impl Debug for Alignment;
impl TryFrom<NonZero<usize>> for Alignment;
impl TryFrom<usize> for Alignment;
impl From<Alignment> for NonZero<usize>;
impl From<Alignment> for usize;
impl Ord for Alignment;
impl PartialOrd for Alignment;
impl Hash for Alignment;
impl Default for Alignment;

Things not getting stabilized

Remains under ptr_alignment_type (but with a new tracking issue: #165719):

// in `core::mem`
impl Alignment {
    pub const fn log2(self) -> u32;
    pub const fn mask(self) -> usize;
}

// in `core::layout`
impl Layout {
    // `pub const fn from_size_align(size: usize, align: usize) -> Result<Self, LayoutError>`'s sibling
    pub const fn from_size_alignment(size: usize, alignment: Alignment) -> Result<Self, LayoutError>;
    // `pub const unsafe fn from_size_align_unchecked(size: usize, align: usize) -> Self`'s sibling
    pub const unsafe fn from_size_alignment_unchecked(size: usize, alignment: Alignment) -> Self;
    // `pub const fn align(&self) -> usize`'s sibling
    pub const fn alignment(&self) -> Alignment;
    // `pub const fn align_to(&self, align: usize) -> Result<Self, LayoutError>`'s sibling
    pub const fn adjust_alignment_to(&self, alignment: Alignment) -> Result<Self, LayoutError>;
    // no `align: usize` sibling
    pub const fn padding_needed_for(&self, alignment: Alignment) -> usize;
}

Removed:

// in core::ptr
#[deprecated(note = "moved from `ptr` to `mem`")]
pub type Alignment = mem::Alignment;

// in `core::mem`
impl Alignment {
    #[deprecated(note = "renamed to `as_nonzero_usize`", suggestion = "as_nonzero_usize" )]
    pub const fn as_nonzero(self) -> NonZero<usize> {
        self.as_nonzero_usize()
    }
}

const trait impls

These are stabilized as non-const (see "Stabilized APIs"), but const counterparts remain unstable under the same feature gates:

under const_convert (#143773)

impl const TryFrom<NonZero<usize>> for Alignment;
impl const TryFrom<usize> for Alignment;
impl const From<Alignment> for NonZero<usize>;
impl const From<Alignment> for usize;

under const_default (#143894).

impl const Default for Alignment;

under const_cmp (#143800).

impl const PartialOrd for Alignment;
impl const Ord for Alignment;
impl const PartialEq for Alignment;
impl const Eq for Alignment;

under const_clone (#142757).

impl const Clone for Alignment;

[rustbot]

r? @Mark-Simulacrum

rustbot has assigned @Mark-Simulacrum.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: @scottmcm, libs
• @scottmcm, libs expanded to 8 candidates
• Random selection from Mark-Simulacrum, joboet, scottmcm

[GrigorenkoPV]

For reasons behind what exactly is being stabilized, why moved from core::ptr to core::mem, and why renamed from as_nonzero to as_nonzero_usize see the discussion on the tracking issue starting with this comment:
#102070 (comment)

@rustbot label -T-libs +T-libs-api +I-libs-api-nominated

[GrigorenkoPV]

This currently fails due to bumpalo having an internal padding_needed_for method in its UnstableLayoutMethods trait, but their method accepts an usize instead of Alignment.

So we either have to change our name, patch bumpalo locally, or convince bumpalo to change their and wait until this repo updates to a newer version of bumpalo.

[clarfonthey]

So, part of the reason why I suggested just stabilising the type instead of, for example, the Layout methods is so that it could be used in new stable APIs without worrying about extra potential conflicts like that. I would argue that the bumpalo conflict is a compelling argument to hold off on stabilising those for now.

[GrigorenkoPV]

Good argument, I've updated the PR and the description accordingly.

[clarfonthey]

Side note: it's kind of bad form to stabilise stuff under one flag while keeping other methods unstable. You can just name the stuff left out as ptr_alignment_type_extras or something, or if you want to make things a bit clearer:

• log2: alignment_type_extras
• Layout methods: layout_alignment_methods

(ptr_alignment doesn't make sense any more if this is moved to mem::Alignment)

---

Rereading the PR, you did already rename the feature flags, so, my bad. You can do this suggestion to further separate the names if you want, but it's not actually as necessary as I thought it was, since the stable/unstable features are different.

[nia-e]

This was discussed in today's @rust-lang/libs-api meeting and we concluded that we'd like to see the methods on Layout stabilised also. There seemed to be some discussion in the tracking issue regarding which module to place everything in, but there was consensus on everything living in core::mem.

[tgross35]

Could the renames and moves be split to a separate PR from stabilization? There is a lot going on here at once.

We also don't need to add deprecated methods/aliases IMO. Users of unstable API need to be aware that there will occasionally be breaking changes, we shouldn't take on the extra burden of trying to smooth this except in rare cases.

[scottmcm]

(Came here from the meeting notes) I'd proposed the partial here, @nia-e, because I figured some pieces of this were "obvious" (assuming we want the type at all) like new+new_unchecked+as_nonzero, at least under some spelling*, but things like Alignment::mask or Layout::padding_needed_for are currently under the same feature gate and not as obviously necessary as part of the original stabilization.

I'm perfectly happy to see more stabilized if folks are happy with it :)

[scottmcm]

Oh, and +💯 to separating out the move from any stabilizations. That can be landed easily without FCP, but with the mir-opt implications and such it's noisy so valuable to have separate from the feature gating changes.

[GrigorenkoPV]

Rebased, changed the bound to ?Sized (same as on core::mem::align_of_val* methods), updated pr description.

@rustbot ready

[clarfonthey]

Edited the existing tracking issues to match feature moves, but one last ask: as part of an ongoing effort, could you open a new tracking issue for the remaining unstable methods on Layout so that we don't have any confusion about what's stable? (We would close the current one once this merges.) Once you do that and update the tracking issue on the feature (maybe giving it a new feature name), everything else looks good to me.

r? clarfonthey

@rustbot author

[GrigorenkoPV]

Edited the existing tracking issues to match feature moves, but one last ask: as part of an ongoing effort, could you open a new tracking issue for the remaining unstable methods on Layout so that we don't have any confusion about what's stable? (We would close the current one once this merges.) Once you do that and update the tracking issue on the feature (maybe giving it a new feature name), everything else looks good to me.

The current PR is keep non-stabilized things under the old feature name, and it's the newly-stabilized things that get a new feature name. Maybe it would make more sense to instead put non-stabilized APIs (that still have the old ptr_alignment_type feature gate) into #102070 and make a new issue for the ones that get a new feature gate and get stabilized?

[clarfonthey]

I guess part of my issue is that we tend to accumulate old discussions on already stabilized things to the point where status gets confusing, and strictly speaking, making a new issue to just close it is kind of pointless. (In particular, because the tracking issue ID never actually makes it onto any new features, since stable features don't use issue IDs.)

So, I would prefer to close the existing issue and make a new one with a new issue so it's clear the scope is smaller, but I guess in this case I would be amenable to just editing the current one since it hasn't picked up a lot of discussion yet.

So, I am fine just merging this if you don't want to move to a new issue, but I would prefer to do that.

[GrigorenkoPV]

Created #165719, update the PR description and the PR contents to reflect the new tracking issue numbers.

@rustbot ready

[clarfonthey]

@rustbot author

(RIP)

[clarfonthey]

@bors r+ rollup

Thank you! (and, well, if CI fails, we'll try again)

[rust-bors]

📌 Commit a8dd244 has been tentatively approved by clarfonthey

It will be put into the queue for this repository once PR CI succeeds.

[rust-bors]

❌ Commit a8dd244 has been unapproved due to PR CI failure. Reapprove it with @bors r+ force if you want to ignore the failure.

View changes since this unapproval

[GrigorenkoPV]

I'm tired, boss

[clarfonthey]

@bors r+

[rust-bors]

📌 Commit 95309cb has been tentatively approved by clarfonthey

It will be put into the queue for this repository once PR CI succeeds.

[rust-bors]

❌ Commit 95309cb has been unapproved due to PR CI failure. Reapprove it with @bors r+ force if you want to ignore the failure.

View changes since this unapproval

[clarfonthey]

@bors retry

[rust-bors]

❗ You can only retry pull requests that are approved and have a previously failed auto build.

Hint: If you wanted to retry pull request CI instead, push the latest commit again, or close and then reopen this PR.

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[clarfonthey]

@bors r+

[rust-bors]

📌 Commit 6e05a38 has been approved by clarfonthey

It is now in the queue for this repository.

[scottmcm]

I'm tired, boss

Yeah, changing features names for staying-unstable features can be a real pain.

(I like partial stabilizing under new ones, personally, so the still-unstable stuff stays the same, but I know there are also reasons for the opposite.)