Specify #[repr(transparent)]

text/0000-repr-transparent.md

@@ -0,0 +1,71 @@
+- Feature Name: `repr_transparent`
+- Start Date: 2016-09-26
+- RFC PR: (leave this empty)
+- Rust Issue: (leave this empty)
+
+# Summary
+[summary]: #summary
+
+Extend the existing `#[repr]` attribute on newtypes with a `transparent` option
+specifying that the type representation is the representation of its only field.
+
+# Motivation
+[motivation]: #motivation
+
+On some ABIs, structures with one field aren't handled the same way as values of
+the same type as the single field. For example on ARM64, functions returning
+a structure with a single `f64` field return nothing and take a pointer to be
+filled with the return value, whereas functions returning a `f64` return the
+floating-point number directly.
+
+# Detailed design
+[design]: #detailed-design
+
+The `#[repr]` attribute on newtypess will be extended to include a form such as:
+
+```rust
+#[repr(transparent)]
+struct TransparentNewtype(f64);
+```
+
+This structure will still have the same representation as a raw `f64` value.
+
+Syntactically, the `repr` meta list will be extended to accept a meta item
+with the name "transparent". This attribute can be placed only on newtypes,
+which means structures (and structure tuples) with a single field.
+
+Some examples of `#[repr(transparent)]` are:
+
+```rust
+// Transparent struct tuple.
+#[repr(transparent)]
+struct TransparentStructTuple(i32);
+
+// Transparent structure.
+#[repr(transparent)]
+struct TransparentStructure { only_field: f64 }
+```
+
+This new representation is mostly useful when the structure it is put on must be
+used in FFI context as a wrapper to the underlying type without actually being
+affected by any ABI semantics.
+
+It is also useful for `AtomicUsize`-like types, which [RFC 1649] states should
+have the same representation as their underlying types.
+
+[RFC 1649]: https://github.com/rust-lang/rfcs/pull/1649
+
+# Drawbacks
+[drawbacks]: #drawbacks
+
+None.
+
+# Alternatives
+[alternatives]: #alternatives
+
+None.
+
+# Unresolved questions
+[unresolved]: #unresolved-questions
+
+None.