From 341005b55917e8d137cb9a8b08554d5977b8b231 Mon Sep 17 00:00:00 2001 From: Yuki Okushi Date: Wed, 27 Jul 2022 20:51:00 +0900 Subject: [PATCH 1/2] Update the `repr(transparent)` section to reflect the current state Signed-off-by: Yuki Okushi --- src/other-reprs.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/src/other-reprs.md b/src/other-reprs.md index 93da7297..c17f0ac7 100644 --- a/src/other-reprs.md +++ b/src/other-reprs.md @@ -56,24 +56,27 @@ compiled as normal.) ## repr(transparent) -This can only be used on structs with a single non-zero-sized field (there may -be additional zero-sized fields). The effect is that the layout and ABI of the -whole struct is guaranteed to be the same as that one field. +This can only be used on structs with a single non-zero-sized field +or enums with only one non-zero-sized field (there may be additional zero-sized fields). +The effect is that the layout and ABI of the whole struct/enum is guaranteed to be the same as that one field. + +> NOTE: There's a `transparent_unions` nightly feature to apply `repr(transparent)` to unions, +> but it hasn't been stabilized due to design concerns. See the [tracking issue][issue-60405] for more details. The goal is to make it possible to transmute between the single field and the -struct. An example of that is [`UnsafeCell`], which can be transmuted into +struct/enum. An example of that is [`UnsafeCell`], which can be transmuted into the type it wraps ([`UnsafeCell`] also uses the unstable [no_niche][no-niche-pull], so its ABI is not actually guaranteed to be the same when nested in other types). -Also, passing the struct through FFI where the inner field type is expected on -the other side is guaranteed to work. In particular, this is necessary for `struct -Foo(f32)` to always have the same ABI as `f32`. +Also, passing the struct/enum through FFI where the inner field type is expected on +the other side is guaranteed to work. In particular, this is necessary for +`struct Foo(f32)` or `enum Foo { Bar(f32) }` to always have the same ABI as `f32`. This repr is only considered part of the public ABI of a type if either the single field is `pub`, or if its layout is documented in prose. Otherwise, the layout should not be relied upon by other crates. -More details are in the [RFC][rfc-transparent]. +More details are in the [RFC 1758][rfc-transparent] and the [RFC 2645][rfc-transparent-unions-enums]. ## repr(u*), repr(i*) @@ -153,8 +156,10 @@ This is a modifier on `repr(C)` and `repr(Rust)`. It is incompatible with [unsafe code guidelines]: https://rust-lang.github.io/unsafe-code-guidelines/layout.html [drop flags]: drop-flags.html [ub loads]: https://github.com/rust-lang/rust/issues/27060 +[issue-60405]: https://github.com/rust-lang/rust/issues/60405 [`UnsafeCell`]: ../std/cell/struct.UnsafeCell.html [rfc-transparent]: https://github.com/rust-lang/rfcs/blob/master/text/1758-repr-transparent.md +[rfc-transparent-unions-enums]: https://rust-lang.github.io/rfcs/2645-transparent-unions.html [really-tagged]: https://github.com/rust-lang/rfcs/blob/master/text/2195-really-tagged-unions.md [rust-bindgen]: https://rust-lang.github.io/rust-bindgen/ [cbindgen]: https://github.com/eqrion/cbindgen From 7df62756a17fe5605ab437fd27ba8b69bb885e59 Mon Sep 17 00:00:00 2001 From: Yuki Okushi Date: Tue, 16 Aug 2022 07:01:41 +0900 Subject: [PATCH 2/2] Apply a suggestion Co-authored-by: Eric Huss --- src/other-reprs.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/other-reprs.md b/src/other-reprs.md index c17f0ac7..228b22bd 100644 --- a/src/other-reprs.md +++ b/src/other-reprs.md @@ -56,8 +56,7 @@ compiled as normal.) ## repr(transparent) -This can only be used on structs with a single non-zero-sized field -or enums with only one non-zero-sized field (there may be additional zero-sized fields). +`#[repr(transparent)]` can only be used on a struct or single-variant enum that has a single non-zero-sized field (there may be additional zero-sized fields). The effect is that the layout and ABI of the whole struct/enum is guaranteed to be the same as that one field. > NOTE: There's a `transparent_unions` nightly feature to apply `repr(transparent)` to unions,