From 54ba23be1c3357c4e9b5a876f572bdaacc45d8b2 Mon Sep 17 00:00:00 2001 From: Jack Wrenn Date: Tue, 10 Oct 2023 19:37:30 +0000 Subject: [PATCH] document zerocopy's relationship to Project Safe Transmute Fixes #480 --- README.md | 24 ++++++++++++++++++++++++ src/lib.rs | 24 ++++++++++++++++++++++++ 2 files changed, 48 insertions(+) diff --git a/README.md b/README.md index 143b4674c38..488a8f37975 100644 --- a/README.md +++ b/README.md @@ -107,6 +107,30 @@ memory model, and *any future memory model*. We ensure this by: [Miri]: https://github.com/rust-lang/miri [Kani]: https://github.com/model-checking/kani +## Relationship to Project Safe Transmute + +[Project Safe Transmute] is an official initiative of the Rust Project to +develop language-level support for safer transmutation. The Project consults +with crates like zerocopy to identify aspects of safer transmutation that +would benefit from compiler support, and has developed an [experimental, +compiler-supported analysis][mcp-transmutability] of when a value of one +type is soundly transmutable into another. Once this functionality is +sufficiently mature, zerocopy intends to replace its internal +transmutability analysis with the compiler-supported one. This change will +likely be solely an implementation detail that is invisible to zerocopy's +users. + +However, Project Safe Transmute will not replace the need for most of +zerocopy's higher-level abstractions over transmutability. The experimental +compiler analysis is a tool for checking the soundness of `unsafe` code—not +a tool to avoid writing `unsafe` code altogether. For the foreseeable +future, crates like zerocopy will still be required in order to provide +higher-level abstractions on top of the building block provided by Project +Safe Transmute. + +[Project Safe Transmute]: https://rust-lang.github.io/rfcs/2835-project-safe-transmute.html +[mcp-transmutability]: https://github.com/rust-lang/compiler-team/issues/411 + ## Disclaimer Disclaimer: Zerocopy is not an officially supported Google product. diff --git a/src/lib.rs b/src/lib.rs index c7c08999797..985bde434d3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -105,6 +105,30 @@ //! //! [Miri]: https://github.com/rust-lang/miri //! [Kani]: https://github.com/model-checking/kani +//! +//! # Relationship to Project Safe Transmute +//! +//! [Project Safe Transmute] is an official initiative of the Rust Project to +//! develop language-level support for safer transmutation. The Project consults +//! with crates like zerocopy to identify aspects of safer transmutation that +//! would benefit from compiler support, and has developed an [experimental, +//! compiler-supported analysis][mcp-transmutability] of when a value of one +//! type is soundly transmutable into another. Once this functionality is +//! sufficiently mature, zerocopy intends to replace its internal +//! transmutability analysis with the compiler-supported one. This change will +//! likely be solely an implementation detail that is invisible to zerocopy's +//! users. +//! +//! However, Project Safe Transmute will not replace the need for most of +//! zerocopy's higher-level abstractions over transmutability. The experimental +//! compiler analysis is a tool for checking the soundness of `unsafe` code—not +//! a tool to avoid writing `unsafe` code altogether. For the foreseeable +//! future, crates like zerocopy will still be required in order to provide +//! higher-level abstractions on top of the building block provided by Project +//! Safe Transmute. +//! +//! [Project Safe Transmute]: https://rust-lang.github.io/rfcs/2835-project-safe-transmute.html +//! [mcp-transmutability]: https://github.com/rust-lang/compiler-team/issues/411 // Sometimes we want to use lints which were added after our MSRV. // `unknown_lints` is `warn` by default and we deny warnings in CI, so without