Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update the docs for layout guarantees of option-like enums #538

Merged
merged 1 commit into from
Nov 19, 2024
Merged

update the docs for layout guarantees of option-like enums #538

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 20 additions & 25 deletions reference/src/layout/enums.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -295,49 +295,44 @@ apply, as described below.

#### Discriminant elision on Option-like enums

(Meta-note: The content in this section is not fully described by any RFC and is
therefore "non-normative". Parts of it were specified in
[rust-lang/rust#60300]).
(Meta-note: The content in this section have been turned into stable guarantees
[via this
FCP](https://github.com/rust-lang/rust/pull/130628#issuecomment-2402761599).).

[rust-lang/rust#60300]: https://github.com/rust-lang/rust/pull/60300

**Definition.** An **option-like enum** is a 2-variant `enum` where:
**Definition.** The fully monomorphized form of a 2-variant `enum` is called an **option-like enum**
if all of the following are satisfied:

- the `enum` has no explicit `#[repr(...)]`, and
- one variant has a single field, and
- the other variant has no fields (the "unit variant").
- one variant has a single field with a type that guarantees discriminant
elision (to be defined below), and
Comment on lines +306 to +307
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Restricting the definition of an option-like enum based on the type of the single field is quite strange to me. Because I'd think that excludes Option<T> from the definition, because T could be usize or any type without guaranteed discriminant elision.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Option<usize> is indeed excluded. Option<NonZeroUsize> is included.

Copy link
Member Author

@RalfJung RalfJung Nov 16, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@saethlin does this answer your question? I don't think I quite understood the comment, TBH.

Copy link
Member

@saethlin saethlin Nov 16, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Whoops, I didn't notice you'd responded.

The text here is just confusing to me, because what I'm imagining is a reader saying "Is this an option-like enum?":

enum Thing<T> {
    Yes(T),
    No,
}

Because by the text above, Thing<T> is not "an option-like enum" because its single field does not guarantee discriminant elision. This would be though:

enum Thing {
    Yes(NonZeroUsize),
    No,
}

...but directly below this the reference already says that Option<T> is an example of an option-like enum.

🤷

I think you're making an assumption that the reader will interpret words a bit differently when a generic parameter is included. If other can confirm that they have read this and don't find the wording confusing I'm happy to be overruled.

Copy link
Contributor

@chorman0773 chorman0773 Nov 17, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For this reason, in my type-layout docs PR, I chose to separate the idea of "Is an enum for which discriminant elision may apply" (in my text, called a discriminant elision elible) and "A field of this type is subject to discriminant elision" (called elision candidate type). When the two are combined is when the result is guaranteed.
I also note explicitly that the determiniation is post-mono. and explicitly call out both Option<T> and Result<T,E>.

So the first Thing<T> would be a discriminant elision eligible enum, and its elision candidate field is of type T. if we then substitute in T=NonZeroUsize, the layout guarantees would apply, but substituing in T=usize, and it would not.

Copy link
Member Author

@RalfJung RalfJung Nov 17, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am implicitly assuming that we are talking about a fully monomorphic type here. It doesn't make sense to ask about the layout of a generic type. I can make that more explicit (though this may come at the cost of readability). I don't see how splitting this concept into two separate concepts is helpful.

- the other variant has only 1-ZST fields (the "unit variant").

The simplest example is `Option<T>` itself, where the `Some` variant
has a single field (of type `T`), and the `None` variant has no
fields. But other enums that fit that same template fit.
fields. But other enums that fit that same template also qualify, e.g.
`Result<T, ()>` or `Result<(), T>`.

**Definition.** The **payload** of an option-like enum is the single
field which it contains; in the case of `Option<T>`, the payload has
type `T`.

**Definition.** In some cases, the payload type may contain illegal
values, which are called **[niches][niche]**. For example, a value of type `&T`
may never be `NULL`, and hence defines a [niche] consisting of the
bitstring `0`. Similarly, the standard library types [`NonZeroU8`]
and friends may never be zero, and hence also define the value of `0`
as a [niche].

[`NonZeroU8`]: https://doc.rust-lang.org/std/num/struct.NonZeroU8.html

The [niche] values must be disjoint from the values allowed by the validity
invariant. The validity invariant is, as of this writing, the current active
discussion topic in the unsafe code guidelines process. [rust-lang/rust#60300]
specifies that the following types have at least one [niche] (the all-zeros
bit-pattern):
**Definition.** The following payload types have guaranteed discriminant
elision:

* `&T`
* `&mut T`
* `extern "C" fn`
* `Box<T>`
* `extern "ABI" fn` (for arbitrary "ABI")
* `core::num::NonZero*`
* `core::ptr::NonNull<T>`
* `#[repr(transparent)] struct` around one of the types in this list.

**Option-like enums where the payload defines at least one [niche] value
(Meta-note: all these types have at least one bit pattern that is guaranteed be
invalid, and can therefore be used as a "[niche]" when computing the enum layout.
More types have this property, but the *guarantee* described here only applies
to the types listed here.)

**Option-like enums where the payload has guaranteed discriminant elision
are guaranteed to be represented using the same memory layout as their
payload.** This is called **discriminant elision**, as there is no
explicit discriminant value stored anywhere. Instead, [niche] values are
Expand Down
Loading