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.

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

Transparent Unions and Enums #2645

Merged
merged 27 commits into from
Apr 30, 2019
Merged
Changes from all commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
991ea90
Transparent Unions RFC
mjbshaw Feb 25, 2019
e08e4a2
Update text/0000-transparent-unions.md
Centril Feb 25, 2019
f7c332e
Update text/0000-transparent-unions.md
Centril Feb 25, 2019
cb3f671
Update text/0000-transparent-unions.md
Centril Feb 25, 2019
381fcf6
Update text/0000-transparent-unions.md
Centril Feb 25, 2019
eb37cce
Update text/0000-transparent-unions.md
Centril Feb 25, 2019
45be61d
Update text/0000-transparent-unions.md
Centril Feb 25, 2019
582fd15
Update text/0000-transparent-unions.md
Centril Feb 25, 2019
d532738
Update text/0000-transparent-unions.md
Centril Feb 25, 2019
4529a95
Update text/0000-transparent-unions.md
Centril Feb 25, 2019
bb73505
Update text/0000-transparent-unions.md
Centril Feb 25, 2019
f9b9d8e
Update text/0000-transparent-unions.md
Centril Feb 25, 2019
1bce145
Update text/0000-transparent-unions.md
Centril Feb 25, 2019
f751ad3
Update text/0000-transparent-unions.md
Centril Feb 25, 2019
7250c02
Update text/0000-transparent-unions.md
Centril Feb 25, 2019
bea3b9f
Revise mentions of transparent enums
mjbshaw Feb 25, 2019
038829b
Remove unnecessary "do nothing" alternative
mjbshaw Feb 25, 2019
c532471
Clarify generic ZST transparent unions
mjbshaw Feb 25, 2019
541934e
Add missing "union" word
mjbshaw Feb 25, 2019
8c92dec
Add some initial text about transparent enums
mjbshaw Feb 26, 2019
18ecba9
s/method/function/
mjbshaw Feb 27, 2019
26d47b7
Fix indentation
mjbshaw Feb 27, 2019
4c88177
Document the behavior of nonnull-style optimization
mjbshaw Mar 9, 2019
ce8b569
Fix typo: union -> enum
Centril Mar 10, 2019
1488266
Mention that FFI can lead to UB if values are uninit
mjbshaw Mar 17, 2019
2afd342
Merge branch 'transparent_unions' of github.com:mjbshaw/rfcs into tra…
mjbshaw Mar 17, 2019
bf09395
RFC 2645
Centril Apr 30, 2019
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
229 changes: 229 additions & 0 deletions text/2645-transparent-unions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,229 @@
- Feature Name: `transparent_enunions`
- Start Date: 2019-02-13
- RFC PR: [rust-lang/rfcs#2645](https://github.com/rust-lang/rfcs/pull/2645)
- Rust Issue: [rust-lang/rust#60405](https://github.com/rust-lang/rust/issues/60405)

# Summary
[summary]: #summary

Allow `#[repr(transparent)]` on `union`s and univariant `enum`s that have exactly one non-zero-sized field (just like `struct`s).

# Motivation
[motivation]: #motivation

Some `union` types are thin newtype-style wrappers around another type, like `MaybeUninit<T>` (and [once upon a time](https://doc.rust-lang.org/1.28.0/src/core/mem.rs.html#955), `ManuallyDrop<T>`). This type is intended to be used in the same places as `T`, but without being `#[repr(transparent)]` the actual compatibility between it and `T` is left unspecified.

Likewise, some `enum` types only have a single variant, and are similarly thin wrappers around another type.

Making types like these `#[repr(transparent)]` would be useful in certain cases. For example, making the type `Wrapper<T>` (which is a `union` or univariant `enum` with a single field of type `T`) transparent:

- Clearly expresses the intent of the developer.
- Protects against accidental violations of that intent (e.g., adding a new variant or non-ZST field will result in a compiler error).
- Makes a clear API guarantee that a `Wrapper<T>` can be transmuted to a `T` or substituted for a `T` in an FFI function's signature (though users must be careful to not pass uninitialized values through FFI to code where uninitialized values are undefined behavior (like C and C++)).

Transparent `union`s and univariant `enum`s are a nice complement to transparent `struct`s, and this RFC rounds out the `#[repr(transparent)]` feature.

# Guide-level explanation
[guide-level-explanation]: #guide-level-explanation

A `union` may be `#[repr(transparent)]` in exactly the same conditions in which a `struct` may be `#[repr(transparent)]`. An `enum` may be `#[repr(transparent)]` if it has exactly one variant, and that variant matches the same conditions which `struct` requires for transparency. Some concrete illustrations follow.

A union may be `#[repr(transparent)]` if it has exactly one non-zero-sized field:

```rust
// This union has the same representation as `f32`.
#[repr(transparent)]
union SingleFieldUnion {
field: f32,
}

// This union has the same representation as `usize`.
#[repr(transparent)]
union MultiFieldUnion {
field: usize,
nothing: (),
}

// This enum has the same representation as `f32`.
#[repr(transparent)]
enum SingleFieldEnum {
Variant(f32)
}

// This enum has the same representation as `usize`.
#[repr(transparent)]
enum MultiFieldEnum {
Variant { field: usize, nothing: () },
}
```

For consistency with transparent `struct`s, `union`s and `enum`s must have exactly one non-zero-sized field. If all fields are zero-sized, the `union` or `enum` must not be `#[repr(transparent)]`:

```rust
// This (non-transparent) union is already valid in stable Rust:
pub union GoodUnion {
pub nothing: (),
}

// This (non-transparent) enum is already valid in stable Rust:
pub enum GoodEnum {
Nothing,
}

// Error: transparent union needs exactly one non-zero-sized field, but has 0
#[repr(transparent)]
pub union BadUnion {
pub nothing: (),
}

// Error: transparent enum needs exactly one non-zero-sized field, but has 0
#[repr(transparent)]
pub enum BadEnum {
Nothing(()),
}

// Error: transparent enum needs exactly one non-zero-sized field, but has 0
#[repr(transparent)]
pub enum BadEmptyEnum {
Nothing,
}
```

The one exception is if the `union` or `enum` is generic over `T` and has a field of type `T`, it may be `#[repr(transparent)]` even if `T` is a zero-sized type:

```rust
// This union has the same representation as `T`.
#[repr(transparent)]
pub union GenericUnion<T: Copy> { // Unions with non-`Copy` fields are unstable.
pub field: T,
pub nothing: (),
}

// This enum has the same representation as `T`.
#[repr(transparent)]
pub enum GenericEnum<T> {
Variant(T, ()),
}

// This is okay even though `()` is a zero-sized type.
pub const THIS_IS_OKAY: GenericUnion<()> = GenericUnion { field: () };
pub const THIS_IS_OKAY_TOO: GenericEnum<()> = GenericEnum::Variant((), ());
```

Transparent `enum`s have the addtional restriction that they require exactly one variant:

```rust
// Error: transparent enum needs exactly one variant, but has 0
#[repr(transparent)]
pub enum TooFewVariants {
}

// Error: transparent enum needs exactly one variant, but has 2
#[repr(transparent)]
pub enum TooManyVariants {
First(usize),
Second(usize),
}
```

# Reference-level explanation
[reference-level-explanation]: #reference-level-explanation

The logic controlling whether a `union` of type `U` may be `#[repr(transparent)]` should match the logic controlling whether a `struct` of type `S` may be `#[repr(transparent)]` (assuming `U` and `S` have the same generic parameters and fields). An `enum` of type `E` may be `#[repr(transparent)]` if it has exactly one variant, and that variant follows all the rules and logic controlling whether a `struct` of type `S` may be `#[repr(transparent)]` (assuming `E` and `S` have the same generic parameters, and `E`'s variant and `S` have the same and fields).

Like transarent `struct`s, a transparent `union` of type `U` and transparent `enum` of type `E` have the same layout, size, and ABI as their single non-ZST field. If they are generic over a type `T`, and all their fields are ZSTs except for exactly one field of type `T`, then they have the same layout and ABI as `T` (even if `T` is a ZST when monomorphized).

Like transparent `struct`s, transparent `union`s and `enum`s are FFI-safe if and only if their underlying representation type is also FFI-safe.

A `union` may not be eligible for the same nonnull-style optimizations that a `struct` or `enum` (with the same fields) are eligible for. Adding `#[repr(transparent)]` to `union` does not change this. To give a more concrete example, it is unspecified whether `size_of::<T>()` is equal to `size_of::<Option<T>>()`, where `T` is a `union` (regardless of whether it is transparent). The Rust compiler is free to perform this optimization if possible, but is not required to, and different compiler versions may differ in their application of these optimizations.

# Drawbacks
[drawbacks]: #drawbacks

`#[repr(transparent)]` on a `union` or `enum` is of limited use. There are cases where it is useful, but they're not common and some users might unnecessarily apply `#[repr(transparent)]` to a type in a cargo-cult fashion.

# Rationale and alternatives
[alternatives]: #alternatives

It would be nice to make `MaybeUninit<T>` `#[repr(transparent)]`. This type is a `union`, and thus this RFC is required to allow making it transparent. One example in which a transparent representation would be useful is for unused parameters in an FFI-function:

```rust
#[repr(C)]
struct Context {
// Imagine there a few fields here, defined by an external C library.
}

extern "C" fn log_event(message: core::ptr::NonNull<libc::c_char>,
context: core::mem::MaybeUninit<Context>) {
// Log the message here, but ignore the context since we don't need it.
}

fn main() {
extern "C" {
fn set_log_handler(handler: extern "C" fn(core::ptr::NonNull<libc::c_char>,
Context));
}

// Set the log handler so the external C library can call log_event.
unsafe {
// Transmuting is safe since MaybeUninit<Context> and Context
// have the same ABI.
set_log_handler(core::mem::transmute(log_event as *const ()));
}

// We can call it too. And since we don't care about the context and
// we're using MaybeUninit, we don't have to pay any extra cost for
// initializing something that's unused.
log_event(core::ptr::NonNull::new(b"Hello, world!\x00".as_ptr() as *mut _).unwrap(),
core::mem::MaybeUninit::uninitialized());
}
```

It is also useful for consuming pointers to uninitialized memory:

```rust
#[repr(C)]
struct Cryptor {
// Imagine there a few fields here, defined by an external C library.
}

// This function may be called from C (or Rust!), and matches the C
// function signature: bool(Cryptor *cryptor)
pub extern "C" fn init_cryptor(cryptor: &mut core::mem::MaybeUninit<Cryptor>) -> bool {
// Initialize the cryptor and return whether we succeeded
}
```

# Prior art
[prior-art]: #prior-art

See [the discussion on RFC #1758](https://github.com/rust-lang/rfcs/pull/1758) (which introduced `#[repr(transparent)]`) for some discussion on applying the attribute to a `union` or `enum`. A summary of the discussion:

[nagisa_1]: https://github.com/rust-lang/rfcs/pull/1758#discussion_r80436621
> + **[nagisa][nagisa_1]:** "Why not univariant unions and enums?"
> + **nox:** "I tried to be conservative for now given I don't have a use case for univariant unions and enums in FFI context."

[eddyb_1]: https://github.com/rust-lang/rfcs/pull/1758#issuecomment-254872520
> + **[eddyb][eddyb_1]:** "I found another important usecase: for `ManuallyDrop<T>`, to be useful in arrays (i.e. small vector optimizations), it needs to have the same layout as `T` and AFAICT `#[repr(C)]` is not guaranteed to do the right thing"
> + **retep998:** "So we'd need to be able to specify `#[repr(transparent)]` on unions?"
> + **eddyb:** "That's the only way to be sure AFAICT, yes."

[joshtriplett_1]: https://github.com/rust-lang/rfcs/pull/1758#issuecomment-274670231
> + **[joshtriplett][joshtriplett_1]:** "In terms of interactions with other features, I think this needs to specify what happens if you apply it to a union with one field, a union with multiple fields, a struct (tuple or otherwise) with multiple fields, a single-variant enum with one field, an enum struct variant where the enum uses `repr(u32)` or similar. The answer to some of those might be "compile error", but some of them (e.g. the union case) may potentially make sense in some contexts."

[pnkfelix_1]: https://github.com/rust-lang/rfcs/pull/1758#issuecomment-290757356
> + **[pnkfelix][pnkfelix_1]:** "However, I personally do not think we need to expand the scope of the feature. So I am okay with leaving it solely defined on `struct`, and leave `union`/`enum` to a follow-on RFC later. (Much the same with a hypothetical `newtype` feature.)"

In summary, many of the questions regarding `#[repr(transparent)]` on a `union` or `enum` were the same as applying it to a multi-field `struct`. These questions have since been answered, so there should be no problems with applying those same answers to `union` univariant `enum`.

# Unresolved questions
[unresolved]: #unresolved-questions

The role of `#[repr(transparent)]` in nonnull-style optimizations is not entirely clear. Specifically, it is unclear whether the user can rely on these optimizations to be performed when they make a type transparent. [Transparent `union`s somewhat complicate the matter](https://github.com/rust-lang/rfcs/pull/2645#issuecomment-470699497). General concensus seems to be that the compiler is free to decide where and when to perform nonnull-style optimizations on `union`s (regardless of whether or not the `union` is transaprent), and no guarantees are made to the user about when and if those optimizations will be applied. It is still an open question exactly what guarantees (if any) Rust makes about transparent `struct`s (and `enum`s) and nonnull-style optimizations.

This RFC doesn't propose any changes to transparent `struct`s, and so does not strictly depend on this question being resolved. But since this RFC is attempting to round out the `#[repr(transparent)]` feature, it seems reasonable to dedicate some time to attempting to round out the guarantees about `#[repr(transparent)]` on `struct`s.

# Future possibilities
[future-possibilities]: #future-possibilities

If a `union` has multiple non-ZST fields, a future RFC could propose a way to choose the representation of that `union` ([example](https://internals.rust-lang.org/t/pre-rfc-transparent-unions/9441/6)).