google / google/zerocopy

Relax `Immutable` semantics

Open
#1,155 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
2.6k
Forks
179
Avg merge
1d 19h
Merged PRs (30d)
29

Description

## Overview

## Progress

- [x] Restrict `Immutable` documentation so that it requires recursive freedom from interior mutability, not just shallow
- [x] Relax `Immutable` documentation so that it refers only to interior mutability
- [x] Relax `Immutable` documentation so that it promises *nothing* to callers outside of zerocopy
- [ ] Update this issue description based on [this comment](https://github.com/google/zerocopy/issues/1155#issuecomment-2098750570)
- [ ] Once `Freeze` is stabilized, consider whether or not `Immutable` needs to have the same semantics as `Freeze`
- [ ] Once `Freeze` is stabilized, add section to `Immutable` documentation entitled something like "Why not `Freeze`?"
- [ ] Get formal semantics of "interior mutability" documented in the Rust reference or stdlib docs
- [ ] Document in the reference or stdlib docs that certain operations are guaranteed sound depending *only* on whether interior mutation happens at runtime, and not on whether the type system believes that `UnsafeCell`s exist at certain offsets or covering certain ranges
- [ ] Update `Immutable` documentation to refer to this formal notion of interior mutability
- [ ] Update use sites to rely only on this soundness guarantee
- [ ] Permit `UnsafeCell`s in some places as appropriate (e.g., introduce a wrapper type which "disables" interior mutability)

## Details

### Intuitive definition of interior mutability + compiler optimizations

TODO:
- Provide an intuitive description of interior mutability and discuss how it relates to the compiler's right to make certain assumptions or optimizations
- Mention that there is currently no formal definition of interior mutability

### Interior mutability vs `UnsafeCell`s

TODO: Describe how interior mutability is implemented via `UnsafeCell`s today, and justify our intention to relax `Immutable`'s requirements in the future to *only* mention interior mutability, not `UnsafeCell`s in particular.

### Stacked Borrows, `UnsafeCell` overlap, and Ralf's future plans

TODO:
- Describe how Stacked Borrows reasons about `UnsafeCell` overlap
- Describe Ralf's intended formal semantics and how it diverges from Stacked Borrows

### `Immutable` vs `Freeze`

EDIT: Maybe not? https://github.com/google/zerocopy/issues/1155#issuecomment-2098750570

TODO:
- Explain why, in order to support general Safe Transmute, `Immutable` must be recursive, while the stdlib `Freeze` will not be recursive
- Conclude that we can never replace `Immutable` with `Freeze`

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.