@ -39,7 +39,7 @@ Topics that are within the scope of this book include: the meaning of (un)safety
The Rustonomicon is not a place to exhaustively describe the semantics and guarantees of every single API in the standard library, nor is it a place to exhaustively describe every feature of Rust.
The Rustonomicon is not a place to exhaustively describe the semantics and guarantees of every single API in the standard library, nor is it a place to exhaustively describe every feature of Rust.
Unless otherwise noted, Rust code in this book uses the Rust 2018 edition.
Unless otherwise noted, Rust code in this book uses the Rust 2021 edition.
This can only be used on structs with a single non-zero-sized field (there may
`#[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).
be additional zero-sized fields). The effect is that the layout and ABI of the
The effect is that the layout and ABI of the whole struct/enum is guaranteed to be the same as that one field.
whole struct 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
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],
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).
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
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
the other side is guaranteed to work. In particular, this is necessary for
Foo(f32)` to always have the same ABI as `f32`.
`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
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
field is `pub`, or if its layout is documented in prose. Otherwise, the layout should
not be relied upon by other crates.
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*)
## repr(u*), repr(i*)
@ -153,8 +155,10 @@ This is a modifier on `repr(C)` and `repr(Rust)`. It is incompatible with
@ -24,7 +24,7 @@ We do this using `PhantomData`, which is a special marker type. `PhantomData`
consumes no space, but simulates a field of the given type for the purpose of
consumes no space, but simulates a field of the given type for the purpose of
static analysis. This was deemed to be less error-prone than explicitly telling
static analysis. This was deemed to be less error-prone than explicitly telling
the type-system the kind of variance that you want, while also providing other
the type-system the kind of variance that you want, while also providing other
useful things such as the information needed by drop check.
useful things such as auto traits and the information needed by drop check.
Iter logically contains a bunch of `&'a T`s, so this is exactly what we tell
Iter logically contains a bunch of `&'a T`s, so this is exactly what we tell
the `PhantomData` to simulate:
the `PhantomData` to simulate:
@ -106,7 +106,14 @@ that that `Vec<T>` _owns_ values of type `T` (more precisely: may use values of
in its `Drop` implementation), and Rust will thus not allow them to _dangle_ should a
in its `Drop` implementation), and Rust will thus not allow them to _dangle_ should a
`Vec<T>` be dropped.
`Vec<T>` be dropped.
**Adding an extra `_owns_T: PhantomData<T>` field is thus _superfluous_ and accomplishes nothing**.
When a type already has a `Drop impl`, **adding an extra `_owns_T: PhantomData<T>` field
is thus _superfluous_ and accomplishes nothing**, dropck-wise (it still affects variance
and auto-traits).
- (advanced edge case: if the type containing the `PhantomData` has no `Drop` impl at all,
but still has drop glue (by having _another_ field with drop glue), then the
dropck/`#[may_dangle]` considerations mentioned herein do apply as well: a `PhantomData<T>`
field will then require `T` to be droppable whenever the containing type goes out of scope).
___
___
@ -234,14 +241,18 @@ standard library made a utility for itself called `Unique<T>` which:
Here’s a table of all the wonderful ways `PhantomData` could be used:
Here’s a table of all the wonderful ways `PhantomData` could be used:
| Phantom type | `'a` | `T` |
| Phantom type | variance of `'a` | variance of `T` | `Send`/`Sync`<br/>(or lack thereof) | dangling `'a` or `T` in drop glue<br/>(_e.g._, `#[may_dangle] Drop`) |
Good, it doesn't compile! Let's break down what's happening here in detail.
Good, it doesn't compile! Let's break down what's happening here in detail.
First let's look at the new `evil_feeder` function:
First let's look at the `assign` function:
```rust
```rust
fn evil_feeder<T>(input: &mut T, val: T) {
fn assign<T>(input: &mut T, val: T) {
*input = val;
*input = val;
}
}
```
```
@ -315,60 +221,43 @@ All it does is take a mutable reference and a value and overwrite the referent w
What's important about this function is that it creates a type equality constraint. It
What's important about this function is that it creates a type equality constraint. It
clearly says in its signature the referent and the value must be the *exact same* type.
clearly says in its signature the referent and the value must be the *exact same* type.
Meanwhile, in the caller we pass in `&mut &'static str` and `&'spike_str str`.
Meanwhile, in the caller we pass in `&mut &'static str` and `&'world str`.
Because `&mut T` is invariant over `T`, the compiler concludes it can't apply any subtyping
Because `&mut T` is invariant over `T`, the compiler concludes it can't apply any subtyping
to the first argument, and so `T` must be exactly `&'static str`.
to the first argument, and so `T` must be exactly `&'static str`.
The other argument is only an `&'a str`, which *is* covariant over `'a`. So the compiler
This is counter to the `&T` case:
adopts a constraint: `&'spike_str str` must be a subtype of `&'static str` (inclusive),
which in turn implies `'spike_str` must be a subtype of `'static` (inclusive). Which is to say,
`'spike_str` must contain `'static`. But only one thing contains `'static` -- `'static` itself!
This is why we get an error when we try to assign `&spike` to `spike_str`. The
```rust
compiler has worked backwards to conclude `spike_str` must live forever, and `&spike`
fn debug<T:std::fmt::Debug>(a: T, b: T) {
simply can't live that long.
println!("a = {a:?} b = {b:?}");
}
```
So even though references are covariant over their lifetimes, they "inherit" invariance
where similarly `a` and `b` must have the same type `T`.
whenever they're put into a context that could do something bad with that. In this case,
But since `&'a T`*is* covariant over `'a`, we are allowed to perform subtyping.
we inherited invariance as soon as we put our reference inside an `&mut T`.
So the compiler decides that `&'static str` can become `&'b str` if and only if
`&'static str` is a subtype of `&'b str`, which will hold if `'static <: 'b`.
This is true, so the compiler is happy to continue compiling this code.
As it turns out, the argument for why it's ok for Box (and Vec, Hashmap, etc.) to
As it turns out, the argument for why it's ok for Box (and Vec, HashMap, etc.) to be covariant is pretty similar to the argument for why it's ok for lifetimes to be covariant: as soon as you try to stuff them in something like a mutable reference, they inherit invariance and you're prevented from doing anything bad.
be covariant is pretty similar to the argument for why it's ok for
lifetimes to be covariant: as soon as you try to stuff them in something like a
mutable reference, they inherit invariance and you're prevented from doing anything
bad.
However Box makes it easier to focus on by-value aspect of references that we
However Box makes it easier to focus on the by-value aspect of references that we partially glossed over.
partially glossed over.
Unlike a lot of languages which allow values to be freely aliased at all times,
Unlike a lot of languages which allow values to be freely aliased at all times, Rust has a very strict rule: if you're allowed to mutate or move a value, you are guaranteed to be the only one with access to it.
Rust has a very strict rule: if you're allowed to mutate or move a value, you
are guaranteed to be the only one with access to it.
Consider the following code:
Consider the following code:
<!-- ignore: simplified code -->
```rust,ignore
```rust,ignore
let mr_snuggles: Box<Cat> = ..;
let hello: Box<&'static str> = Box::new("hello");
let spike: Box<Dog> = ..;
let mut pet: Box<Animal>;
let mut world: Box<&'b str>;
pet = mr_snuggles;
world = hello;
pet = spike;
```
```
There is no problem at all with the fact that we have forgotten that `mr_snuggles` was a Cat,
There is no problem at all with the fact that we have forgotten that `hello` was alive for `'static`,
or that we overwrote him with a Dog, because as soon as we moved mr_snuggles to a variable
because as soon as we moved `hello` to a variable that only knew it was alive for `'b`,
that only knew he was an Animal, **we destroyed the only thing in the universe that
**we destroyed the only thing in the universe that remembered it lived for longer**!
remembered he was a Cat**!
In contrast to the argument about immutable references being soundly covariant because they
don't let you change anything, owned values can be covariant because they make you
change *everything*. There is no connection between old locations and new locations.
Applying by-value subtyping is an irreversible act of knowledge destruction, and
without any memory of how things used to be, no one can be tricked into acting on
that old information!
Only one thing left to explain: function pointers.
Only one thing left to explain: function pointers.
@ -376,43 +265,75 @@ To see why `fn(T) -> U` should be covariant over `U`, consider the following sig
<!-- ignore: simplified code -->
<!-- ignore: simplified code -->
```rust,ignore
```rust,ignore
fn get_animal() -> Animal;
fn get_str() -> &'a str;
```
```
This function claims to produce an Animal. As such, it is perfectly valid to
This function claims to produce a`str` bound by some liftime `'a`. As such, it is perfectly valid to
provide a function with the following signature instead:
provide a function with the following signature instead:
<!-- ignore: simplified code -->
<!-- ignore: simplified code -->
```rust,ignore
```rust,ignore
fn get_animal() -> Cat;
fn get_static() -> &'static str;
```
```
After all, Cats are Animals, so always producing a Cat is a perfectly valid way
So when the function is called, all it's expecting is a `&str` which lives at least the lifetime of `'a`,
to produce Animals. Or to relate it back to real Rust: if we need a function
it doesn't matter if the value actually lives longer.
that is supposed to produce something that lives for `'short`, it's perfectly
fine for it to produce something that lives for `'long`. We don't care, we can
just forget that fact.
However, the same logic does not apply to *arguments*. Consider trying to satisfy:
However, the same logic does not apply to *arguments*. Consider trying to satisfy:
<!-- ignore: simplified code -->
<!-- ignore: simplified code -->
```rust,ignore
```rust,ignore
fn handle_animal(Animal);
fn store_ref(&'a str);
```
```
with:
with:
<!-- ignore: simplified code -->
<!-- ignore: simplified code -->
```rust,ignore
```rust,ignore
fn handle_animal(Cat);
fn store_static(&'static str);
```
```
The first function can accept Dogs, but the second function absolutely can't.
The first function can accept any string reference as long as it lives at least for `'a`,
but the second cannot accept a string reference that lives for any duration less than `'static`,
which would cause a conflict.
Covariance doesn't work here. But if we flip it around, it actually *does*
Covariance doesn't work here. But if we flip it around, it actually *does*
work! If we need a function that can handle Cats, a function that can handle *any*
work! If we need a function that can handle `&'static str`, a function that can handle *any* reference lifetime
Animal will surely work fine. Or to relate it back to real Rust: if we need a
will surely work fine.
function that can handle anything that lives for at least `'long`, it's perfectly
fine for it to be able to handle anything that lives for at least `'short`.
SabrinaJewson
1 year ago