Skip to content

Commit

Permalink
Improve the PhantomData table (#417)
Browse files Browse the repository at this point in the history
  • Loading branch information
@danielhenrymantilla
danielhenrymantilla committed Dec 10, 2023
1 parent 83d0151 commit 360a768
Showing 1 changed file with 23 additions and 12 deletions.
35 changes: 23 additions & 12 deletions src/phantom-data.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
`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).

___

Expand Down Expand Up @@ -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:

| Phantom type | `'a` | `T` | `Send` | `Sync` |
|-----------------------------|-----------|-----------------------------|-----------|-----------|
| `PhantomData<T>` | - | covariant (with drop check) | `T: Send` | `T: Sync` |
| `PhantomData<&'a T>` | covariant | covariant | `T: Sync` | `T: Sync` |
| `PhantomData<&'a mut T>` | covariant | invariant | `T: Send` | `T: Sync` |
| `PhantomData<*const T>` | - | covariant | - | - |
| `PhantomData<*mut T>` | - | invariant | - | - |
| `PhantomData<fn(T)>` | - | contravariant | `Send` | `Sync` |
| `PhantomData<fn() -> T>` | - | covariant | `Send` | `Sync` |
| `PhantomData<fn(T) -> T>` | - | invariant | `Send` | `Sync` |
| `PhantomData<Cell<&'a ()>>` | invariant | - | `Send` | - |
| 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`) |
|-----------------------------|:----------------:|:-----------------:|:-----------------------------------------:|:------------------------------------------------:|
| `PhantomData<T>` | - | **cov**ariant | inherited | disallowed ("owns `T`") |
| `PhantomData<&'a T>` | **cov**ariant | **cov**ariant | `Send + Sync`<br/>requires<br/>`T : Sync` | allowed |
| `PhantomData<&'a mut T>` | **cov**ariant | **inv**ariant | inherited | allowed |
| `PhantomData<*const T>` | - | **cov**ariant | `!Send + !Sync` | allowed |
| `PhantomData<*mut T>` | - | **inv**ariant | `!Send + !Sync` | allowed |
| `PhantomData<fn(T)>` | - | **contra**variant | `Send + Sync` | allowed |
| `PhantomData<fn() -> T>` | - | **cov**ariant | `Send + Sync` | allowed |
| `PhantomData<fn(T) -> T>` | - | **inv**ariant | `Send + Sync` | allowed |
| `PhantomData<Cell<&'a ()>>` | **inv**ariant | - | `Send + !Sync` | allowed |

- Note: opting out of the `Unpin` auto-trait requires the dedicated [`PhantomPinned`] type instead.

[`PhantomPinned`]: ../core/marker/struct.PhantomPinned.html

0 comments on commit 360a768

Please sign in to comment.