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 unions for safe ManuallyDrop assignment. #912

Merged
merged 1 commit into from
Dec 22, 2020
Merged

Update unions for safe ManuallyDrop assignment. #912

Show file tree
Hide file tree
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
23 changes: 14 additions & 9 deletions src/items/unions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,14 +66,18 @@ unsafe {
}
```

Writes to `Copy` union fields do not require reads for running destructors, so
these writes don't have to be placed in `unsafe` blocks
Writes to [`Copy`] or [`ManuallyDrop`][ManuallyDrop] union fields do not
require reads for running destructors, so these writes don't have to be placed
in `unsafe` blocks
Copy link
Member

Choose a reason for hiding this comment

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

The actual implementation goes a bit further, so u.f1.g2 = ... is safe if that assignment is at ManuallyDrop or impl Copy type... but on stable code that is impossible to observe since all fields must be ManuallyDrop or impl Copy. Not if the reference should even mention it, then.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I think it's fine to leave out for now. Is it even possible on nightly to have a non-Copy/ManuallyDrop type?

Copy link
Member

Choose a reason for hiding this comment

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

Yeah, with a feature flag you can use any type without drop glue.

In principle even those could be safe to assign, so we could remove this safety check entirely... for now I went with the smaller change that should just make the safety check unreachable on stable.


```rust
# union MyUnion { f1: u32, f2: f32 }
# let mut u = MyUnion { f1: 1 };
#
# use std::mem::ManuallyDrop;
union MyUnion { f1: u32, f2: ManuallyDrop<String> }
let mut u = MyUnion { f1: 1 };

// These do not require `unsafe`.
u.f1 = 2;
u.f2 = ManuallyDrop::new(String::from("example"));
```

Commonly, code using unions will provide safe wrappers around unsafe union
Expand All @@ -82,9 +86,9 @@ field accesses.
## Unions and `Drop`

When a union is dropped, it cannot know which of its fields needs to be dropped.
For this reason, all union fields must either be of a `Copy` type or of the
shape [`ManuallyDrop<_>`]. This ensures that a union does not need to drop
anything when it goes out of scope.
For this reason, all union fields must either be of a [`Copy`] type or of the
shape [`ManuallyDrop<_>`][ManuallyDrop]. This ensures that a union does not
need to drop anything when it goes out of scope.

Like for structs and enums, it is possible to `impl Drop` for a union to
manually define what happens when it gets dropped.
Expand Down Expand Up @@ -177,4 +181,5 @@ checking, etc etc etc).
[_WhereClause_]: generics.md#where-clauses
[_StructFields_]: structs.md
[`transmute`]: ../../std/mem/fn.transmute.html
[`ManuallyDrop<_>`]: ../../std/mem/struct.ManuallyDrop.html
[`Copy`]: ../../std/marker/trait.Copy.html
[ManuallyDrop]: ../../std/mem/struct.ManuallyDrop.html
8 changes: 5 additions & 3 deletions src/types/union.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,14 @@ a [`union` item][item].

Unions have no notion of an "active field". Instead, every union access
transmutes parts of the content of the union to the type of the accessed
field. Since transmutes can cause unexpected or undefined behaviour, `unsafe` is
required to read from a union field, or to write to a field that doesn't
implement [`Copy`]. See the [item] documentation for further details.
field. Since transmutes can cause unexpected or undefined behaviour, `unsafe`
is required to read from a union field, or to write to a field that doesn't
implement [`Copy`] or has a [`ManuallyDrop`] type. See the [item] documentation
for further details.

The memory layout of a `union` is undefined by default, but the `#[repr(...)]`
attribute can be used to fix a layout.

[`Copy`]: ../special-types-and-traits.md#copy
[`ManuallyDrop`]: ../../std/mem/struct.ManuallyDrop.html
[item]: ../items/unions.md