unions

text/0000-untagged_union.md

@@ -0,0 +1,325 @@
+- Feature Name: `untagged_union`
+- Start Date: 2015-12-29
+- RFC PR: (leave this empty)
+- Rust Issue: (leave this empty)
+
+# Summary
+[summary]: #summary
+
+Provide native support for C-compatible unions, defined via a new keyword
+`untagged_union`.
+
+# Motivation
+[motivation]: #motivation
+
+Many FFI interfaces include unions.  Rust does not currently have any native
+representation for unions, so users of these FFI interfaces must define
+multiple structs and transmute between them via `std::mem::transmute`.  The
+resulting FFI code must carefully understand platform-specific size and
+alignment requirements for structure fields.  Such code has little in common
+with how a C client would invoke the same interfaces.
+
+Introducing native syntax for unions makes many FFI interfaces much simpler and
+less error-prone to write, simplifying the creation of bindings to native
+libraries, and enriching the Rust/Cargo ecosystem.
+
+A native union mechanism would also simplify Rust implementations of
+space-efficient or cache-efficient structures relying on value representation,
+such as machine-word-sized unions using the least-significant bits of aligned
+pointers to distinguish cases.
+
+The syntax proposed here avoids reserving `union` as the new keyword, as
+existing Rust code already uses `union` for other purposes, including [multiple
+functions in the standard
+library](https://doc.rust-lang.org/std/?search=union).
+
+To preserve memory safety, accesses to union fields may only occur in `unsafe`
+code.  Commonly, code using unions will provide safe wrappers around unsafe
+union field accesses.
+
+# Detailed design
+[design]: #detailed-design
+
+## Declaring a union type
+
+A union declaration uses the same field declaration syntax as a `struct`
+declaration, except with the keyword `untagged_union` in place of `struct`:
+
+```rust
+untagged_union MyUnion {
+    f1: u32,
+    f2: f32,
+}
+```
+
+`untagged_union` implies `#[repr(C)]` as the default representation, making
+`#[repr(C)] untagged_union` permissible but redundant.
+
+## Instantiating a union
+
+A union instantiation uses the same syntax as a struct instantiation, except
+that it must specify exactly one field:
+
+```rust
+let u = MyUnion { f1: 1 };
+```
+
+Specifying multiple fields in a union instantiation results in a compiler
+error.
+
+Safe code may instantiate a union, as no unsafe behavior can occur until
+accessing a field of the union.  Code that wishes to maintain invariants about
+the union fields should make the union fields private and provide public
+functions that maintain the invariants.
+
+## Reading fields
+
+Unsafe code may read from union fields, using the same dotted syntax as a
+struct:
+
+```rust
+fn f(u: MyUnion) -> f32 {
+    unsafe { u.f2 }
+}
+```
+
+## Writing fields
+
+Unsafe code may write to fields in a mutable union, using the same syntax as a
+struct:
+
+```rust
+fn f(u: &mut MyUnion) {
+    unsafe {
+        u.f1 = 2;
+    }
+}
+```
+
+If a union contains multiple fields of different sizes, assigning to a field
+smaller than the entire union must not change the memory of the union outside
+that field.
+
+## Pattern matching
+
+Unsafe code may pattern match on union fields, using the same syntax as a
+struct, without the requirement to mention every field of the union in a match
+or use `..`:
+
+```rust
+fn f(u: MyUnion) {
+    unsafe {
+        match u {
+            MyUnion { f1: 10 } => { println!("ten"); }
+            MyUnion { f2 } => { println!("{}", f2); }
+        }
+    }
+}
+```
+
+Matching a specific value from a union field makes a refutable pattern; naming
+a union field without matching a specific value makes an irrefutable pattern.
+Both require unsafe code.
+
+Pattern matching may match a union as a field of a larger structure.  In
+particular, when using an `untagged_union` to implement a C tagged union via
+FFI, this allows matching on the tag and the corresponding field
+simultaneously:
+
+```rust
+#[repr(u32)]
+enum Tag { I, F }
+
+untagged_union U {
+    i: i32,
+    f: f32,
+}
+
+#[repr(C)]
+struct Value {
+    tag: Tag,
+    u: U,
+}
+
+fn is_zero(v: Value) -> bool {
+    unsafe {
+        match v {
+            Value { tag: I, u: U { i: 0 } } => true,
+            Value { tag: F, u: U { f: 0.0 } } => true,
+            _ => false,
+        }
+    }
+}
+```
+
+Note that a pattern match on a union field that has a smaller size than the
+entire union must not make any assumptions about the value of the union's
+memory outside that field.
+
+## Borrowing union fields
+
+Unsafe code may borrow a reference to a field of a union; doing so borrows the
+entire union, such that any borrow conflicting with a borrow of the union
+(including a borrow of another union field or a borrow of a structure
+containing the union) will produce an error.
+
+```rust
+untagged_union U {
+    f1: u32,
+    f2: f32,
+}
+
+#[test]
+fn test() {
+    let mut u = U { f1: 1 };
+    unsafe {
+        let b1 = &mut u.f1;
+	// let b2 = &mut u.f2; // This would produce an error
+        *b1 = 5;
+    }
+    unsafe {
+        assert_eq!(u.f1, 5);
+    }
+}
+```
+
+Simultaneous borrows of multiple fields of a struct contained within a union do
+not conflict:
+
+```rust
+struct S {
+    x: u32,
+    y: u32,
+}
+
+untagged_union U {
+    s: S,
+    both: u64,
+}
+
+#[test]
+fn test() {
+    let mut u = U { s: S { x: 1, y: 2 } };
+    unsafe {
+        let bx = &mut u.s.x;
+        // let bboth = &mut u.both; // This would fail
+        let by = &mut u.s.y;
+        *bx = 5;
+        *by = 10;
+    }
+    unsafe {
+        assert_eq!(u.s.x, 5);
+        assert_eq!(u.s.y, 10);
+    }
+}
+```
+
+## Union and field visibility
+
+The `pub` keyword works on the union and on its fields, as with a struct.  The
+union and its fields default to private.  Using a private field in a union
+instantiation, field access, or pattern match produces an error.
+
+## Uninitialized unions
+
+The compiler should consider a union uninitialized if declared without an
+initializer.  However, providing a field during instantiation, or assigning to
+a field, should cause the compiler to treat the entire union as initialized.
+
+## Unions and traits
+
+A union may have trait implementations, using the same syntax as a struct.
+
+The compiler should warn if a union field has a type that implements the `Drop`
+trait.
+
+## Unions and undefined behavior
+
+Rust code must not use unions to invoke [undefined
+behavior](https://doc.rust-lang.org/nightly/reference.html#behavior-considered-undefined).
+In particular, Rust code must not use unions to break the pointer aliasing
+rules with raw pointers, or access a field containing a primitive type with an
+invalid value.
+
+## Union size and alignment
+
+A union must have the same size and alignment as an equivalent C union
+declaration for the target platform.  Typically, a union would have the maximum
+size of any of its fields, and the maximum alignment of any of its fields.
+Note that those maximums may come from different fields; for instance:
+
+```rust
+untagged_union U {
+    f1: u16,
+    f2: [u8; 4],
+}
+
+#[test]
+fn test() {
+    assert_eq!(std::mem::size_of<U>(), 4);
+    assert_eq!(std::mem::align_of<U>(), 2);
+}
+```
+
+# Drawbacks
+[drawbacks]: #drawbacks
+
+Adding a new type of data structure would increase the complexity of the
+language and the compiler implementation, albeit marginally.  However, this
+change seems likely to provide a net reduction in the quantity and complexity
+of unsafe code.
+
+# Alternatives
+[alternatives]: #alternatives
+
+- Don't do anything, and leave users of FFI interfaces with unions to continue
+  writing complex platform-specific transmute code.
+- Create macros to define unions and access their fields.  However, such macros
+  make field accesses and pattern matching look more cumbersome and less
+  structure-like.  The implementation and use of such macros provides strong
+  motivation to seek a better solution, and indeed existing writers and users
+  of such macros have specifically requested native syntax in Rust.
+- Define unions without a new keyword `untagged_union`, such as via
+  `#[repr(union)] struct`.  This would avoid any possibility of breaking
+  existing code that uses the keyword, but would make declarations more
+  verbose, and introduce potential confusion with `struct` (or whatever
+  existing construct the `#[repr(union)]` attribute modifies).
+- Use a compound keyword like `unsafe union`, while not reserving `union` on
+  its own as a keyword, to avoid breaking use of `union` as an identifier.
+  Potentially more appealing syntax, if the Rust parser can support it.
+- Use a new operator to access union fields, rather than the same `.` operator
+  used for struct fields.  This would make union fields more obvious at the
+  time of access, rather than making them look syntactically identical to
+  struct fields despite the semantic difference in storage representation.
+- The [unsafe enum](https://github.com/rust-lang/rfcs/pull/724) proposal:
+  introduce untagged enums, identified with `unsafe enum`.  Pattern-matching
+  syntax would make field accesses significantly more verbose than structure
+  field syntax.
+- The [unsafe enum](https://github.com/rust-lang/rfcs/pull/724) proposal with
+  the addition of struct-like field access syntax.  The resulting field access
+  syntax would look much like this proposal; however, pairing an enum-style
+  definition with struct-style usage seems confusing for developers.  An
+  enum-based declaration leads users to expect enum-like syntax; a new
+  construct distinct from both enum and struct does not lead to such
+  expectations, and developers used to C unions will expect struct-like field
+  access for unions.
+
+# Unresolved questions
+[unresolved]: #unresolved-questions
+
+Can the borrow checker support the rule that "simultaneous borrows of multiple
+fields of a struct contained within a union do not conflict"?  If not, omitting
+that rule would only marginally increase the verbosity of such code, by
+requiring an explicit borrow of the entire struct first.
+
+Can a pattern match match multiple fields of a union at once?  For rationale,
+consider a union using the low bits of an aligned pointer as a tag; a pattern
+match may match the tag using one field and a value identified by that tag
+using another field.  However, if this complicates the implementation, omitting
+it would not significantly complicate code using unions.
+
+C APIs using unions often also make use of anonymous unions and anonymous
+structs.  For instance, a union may contain anonymous structs to define
+non-overlapping fields, and a struct may contain an anonymous union to define
+overlapping fields.  This RFC does not define anonymous unions or structs, but
+a subsequent RFC may wish to do so.