From 26a029d407be480d791972afb5975cf62c9360a6 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 02:47:55 +0200 Subject: Adding upstream version 124.0.1. Signed-off-by: Daniel Baumann --- third_party/rust/yoke/.cargo-checksum.json | 1 + third_party/rust/yoke/Cargo.toml | 95 ++ third_party/rust/yoke/LICENSE | 44 + third_party/rust/yoke/README.md | 31 + third_party/rust/yoke/src/either.rs | 87 ++ third_party/rust/yoke/src/erased.rs | 41 + third_party/rust/yoke/src/kinda_sorta_dangling.rs | 94 ++ third_party/rust/yoke/src/lib.rs | 66 + third_party/rust/yoke/src/macro_impls.rs | 108 ++ third_party/rust/yoke/src/trait_hack.rs | 318 +++++ third_party/rust/yoke/src/yoke.rs | 1351 +++++++++++++++++++++ third_party/rust/yoke/src/yokeable.rs | 325 +++++ third_party/rust/yoke/src/zero_from.rs | 57 + third_party/rust/yoke/tests/bincode.rs | 83 ++ third_party/rust/yoke/tests/miri.rs | 15 + 15 files changed, 2716 insertions(+) create mode 100644 third_party/rust/yoke/.cargo-checksum.json create mode 100644 third_party/rust/yoke/Cargo.toml create mode 100644 third_party/rust/yoke/LICENSE create mode 100644 third_party/rust/yoke/README.md create mode 100644 third_party/rust/yoke/src/either.rs create mode 100644 third_party/rust/yoke/src/erased.rs create mode 100644 third_party/rust/yoke/src/kinda_sorta_dangling.rs create mode 100644 third_party/rust/yoke/src/lib.rs create mode 100644 third_party/rust/yoke/src/macro_impls.rs create mode 100644 third_party/rust/yoke/src/trait_hack.rs create mode 100644 third_party/rust/yoke/src/yoke.rs create mode 100644 third_party/rust/yoke/src/yokeable.rs create mode 100644 third_party/rust/yoke/src/zero_from.rs create mode 100644 third_party/rust/yoke/tests/bincode.rs create mode 100644 third_party/rust/yoke/tests/miri.rs (limited to 'third_party/rust/yoke') diff --git a/third_party/rust/yoke/.cargo-checksum.json b/third_party/rust/yoke/.cargo-checksum.json new file mode 100644 index 0000000000..ec381584bd --- /dev/null +++ b/third_party/rust/yoke/.cargo-checksum.json @@ -0,0 +1 @@ +{"files":{"Cargo.toml":"ff76fe135064274697b3a55c12cb02454e35bace3c06f7d21e75937baae78149","LICENSE":"853f87c96f3d249f200fec6db1114427bc8bdf4afddc93c576956d78152ce978","README.md":"7caeea392483abdb034071f43cd056c7a69940b77a0e65ad7f37f4657107d4a3","src/either.rs":"cc98640a3b0aa349631c0bf5a54c18ec6e1ee638612b557e35e3a191e9178d42","src/erased.rs":"ebd156e832b5e67c599c6938cfbe85cd11a6088818a6981f56911cffb49e0a5f","src/kinda_sorta_dangling.rs":"178a8185d03c45dbdccdc574aa95777d52d4a36bb224a0d7bc3f29b5de39576a","src/lib.rs":"a143f3e85539a73c909d950bcc20b101af353912b9898d4a5b091fae9fcdd874","src/macro_impls.rs":"f81ac8af77ac3641bfee116d6295f5f756f92d4b3b6c7d43a228cd313174d355","src/trait_hack.rs":"34c6979cbacd85de650ba4a1f4b1cc344451e229172394f289432cdb7a4fa0c0","src/yoke.rs":"99fb6866741ad0d4d704bb167db407cc0aeb5406b24c71fb4be43922023af0e5","src/yokeable.rs":"1b2e04f620ab7c06c557d23c44b7ebb67736ae239c44277f4fbefbacc011e549","src/zero_from.rs":"71d97f87e003db0eb0e97064509bdf9355622ccd655549f926b6a0d9119db3ee","tests/bincode.rs":"3cc3c73af5cd5e44deaf3eb172257d9e2eedbbc5bf4abc4e04648d21bb667f5b","tests/miri.rs":"fd119cfbf1abc39463e3be5145966962853d1f6771826c003449a06b3e8acbea"},"package":"65e71b2e4f287f467794c671e2b8f8a5f3716b3c829079a1c44740148eff07e4"} \ No newline at end of file diff --git a/third_party/rust/yoke/Cargo.toml b/third_party/rust/yoke/Cargo.toml new file mode 100644 index 0000000000..3ba3981fe6 --- /dev/null +++ b/third_party/rust/yoke/Cargo.toml @@ -0,0 +1,95 @@ +# THIS FILE IS AUTOMATICALLY GENERATED BY CARGO +# +# When uploading crates to the registry Cargo will automatically +# "normalize" Cargo.toml files for maximal compatibility +# with all versions of Cargo and also rewrite `path` dependencies +# to registry (e.g., crates.io) dependencies. +# +# If you are reading this file be aware that the original Cargo.toml +# will likely look very different (and much more reasonable). +# See Cargo.toml.orig for the original contents. + +[package] +edition = "2021" +rust-version = "1.67" +name = "yoke" +version = "0.7.3" +authors = ["Manish Goregaokar "] +include = [ + "data/**/*", + "src/**/*", + "examples/**/*", + "benches/**/*", + "tests/**/*", + "Cargo.toml", + "LICENSE", + "README.md", +] +description = "Abstraction allowing borrowed data to be carried along with the backing data it borrows from" +readme = "README.md" +keywords = [ + "zerocopy", + "serialization", + "lifetime", + "borrow", + "self-referential", +] +categories = [ + "data-structures", + "memory-management", + "caching", + "no-std", +] +license-file = "LICENSE" +repository = "https://github.com/unicode-org/icu4x" + +[package.metadata.cargo-all-features] +max_combination_size = 3 + +[package.metadata.docs.rs] +all-features = true + +[package.metadata.workspaces] +independent = true + +[dependencies.serde] +version = "1.0" +optional = true +default-features = false + +[dependencies.stable_deref_trait] +version = "1.2.0" +default-features = false + +[dependencies.yoke-derive] +version = "0.7.3" +optional = true +default-features = false + +[dependencies.zerofrom] +version = "0.1.2" +optional = true +default-features = false + +[dev-dependencies.bincode] +version = "1.3.3" + +[dev-dependencies.serde] +version = "1.0.125" + +[features] +alloc = [ + "stable_deref_trait/alloc", + "serde?/alloc", + "zerofrom/alloc", +] +default = [ + "alloc", + "zerofrom", +] +derive = [ + "dep:yoke-derive", + "zerofrom/derive", +] +serde = ["dep:serde"] +zerofrom = ["dep:zerofrom"] diff --git a/third_party/rust/yoke/LICENSE b/third_party/rust/yoke/LICENSE new file mode 100644 index 0000000000..9845aa5f48 --- /dev/null +++ b/third_party/rust/yoke/LICENSE @@ -0,0 +1,44 @@ +UNICODE LICENSE V3 + +COPYRIGHT AND PERMISSION NOTICE + +Copyright © 2020-2023 Unicode, Inc. + +NOTICE TO USER: Carefully read the following legal agreement. BY +DOWNLOADING, INSTALLING, COPYING OR OTHERWISE USING DATA FILES, AND/OR +SOFTWARE, YOU UNEQUIVOCALLY ACCEPT, AND AGREE TO BE BOUND BY, ALL OF THE +TERMS AND CONDITIONS OF THIS AGREEMENT. IF YOU DO NOT AGREE, DO NOT +DOWNLOAD, INSTALL, COPY, DISTRIBUTE OR USE THE DATA FILES OR SOFTWARE. + +Permission is hereby granted, free of charge, to any person obtaining a +copy of data files and any associated documentation (the "Data Files") or +software and any associated documentation (the "Software") to deal in the +Data Files or Software without restriction, including without limitation +the rights to use, copy, modify, merge, publish, distribute, and/or sell +copies of the Data Files or Software, and to permit persons to whom the +Data Files or Software are furnished to do so, provided that either (a) +this copyright and permission notice appear with all copies of the Data +Files or Software, or (b) this copyright and permission notice appear in +associated Documentation. + +THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY +KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF +THIRD PARTY RIGHTS. + +IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE +BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, +OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, +WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE DATA +FILES OR SOFTWARE. + +Except as contained in this notice, the name of a copyright holder shall +not be used in advertising or otherwise to promote the sale, use or other +dealings in these Data Files or Software without prior written +authorization of the copyright holder. + +— + +Portions of ICU4X may have been adapted from ICU4C and/or ICU4J. +ICU 1.8.1 to ICU 57.1 © 1995-2016 International Business Machines Corporation and others. diff --git a/third_party/rust/yoke/README.md b/third_party/rust/yoke/README.md new file mode 100644 index 0000000000..23c1ac8c38 --- /dev/null +++ b/third_party/rust/yoke/README.md @@ -0,0 +1,31 @@ +# yoke [![crates.io](https://img.shields.io/crates/v/yoke)](https://crates.io/crates/yoke) + + + +This crate provides [`Yoke`][Yoke], which allows one to "yoke" (attach) a zero-copy deserialized +object (say, a [`Cow<'a, str>`](alloc::borrow::Cow)) to the source it was deserialized from, (say, an [`Rc<[u8]>`](alloc::rc::Rc)), +known in this crate as a "cart", producing a type that looks like `Yoke, Rc<[u8]>>` +and can be moved around with impunity. + +Succinctly, this allows one to "erase" static lifetimes and turn them into dynamic ones, similarly +to how `dyn` allows one to "erase" static types and turn them into dynamic ones. + +Most of the time the yokeable `Y` type will be some kind of zero-copy deserializable +abstraction, potentially with an owned variant (like [`Cow`](alloc::borrow::Cow), +[`ZeroVec`](https://docs.rs/zerovec), or an aggregate containing such types), and the cart `C` will be some smart pointer like + [`Box`](alloc::boxed::Box), [`Rc`](alloc::rc::Rc), or [`Arc`](std::sync::Arc), potentially wrapped in an [`Option`](Option). + +The key behind this crate is [`Yoke::get()`], where calling [`.get()`][Yoke::get] on a type like +`Yoke, _>` will get you a short-lived `&'a Cow<'a, str>`, restricted to the +lifetime of the borrow used during [`.get()`](Yoke::get). This is entirely safe since the `Cow` borrows from +the cart type `C`, which cannot be interfered with as long as the `Yoke` is borrowed by [`.get()`](Yoke::get). +[`.get()`](Yoke::get) protects access by essentially reifying the erased lifetime to a safe local one +when necessary. + +See the documentation of [`Yoke`] for more details. + + + +## More Information + +For more information on development, authorship, contributing etc. please visit [`ICU4X home page`](https://github.com/unicode-org/icu4x). diff --git a/third_party/rust/yoke/src/either.rs b/third_party/rust/yoke/src/either.rs new file mode 100644 index 0000000000..6cddd61d79 --- /dev/null +++ b/third_party/rust/yoke/src/either.rs @@ -0,0 +1,87 @@ +// This file is part of ICU4X. For terms of use, please see the file +// called LICENSE at the top level of the ICU4X source tree +// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ). + +//! Types to enable polymorphic carts. + +use crate::CloneableCart; + +use core::ops::Deref; +use stable_deref_trait::StableDeref; + +/// A cart that can be one type or the other. Enables ergonomic polymorphic carts. +/// +/// `EitherCart` enables yokes originating from different data sources and therefore +/// having different cart types to be merged into the same yoke type, but still being +/// able to recover the original cart type if necessary. +/// +/// All relevant Cart traits are implemented for `EitherCart`, and carts can be +/// safely wrapped in an `EitherCart`. +/// +/// Also see [`Yoke::erase_box_cart()`](crate::Yoke::erase_box_cart). +/// +/// # Examples +/// +/// ``` +/// use std::borrow::Cow; +/// use std::rc::Rc; +/// use yoke::either::EitherCart; +/// use yoke::Yoke; +/// +/// let y1: Yoke<&'static str, Rc> = +/// Yoke::attach_to_zero_copy_cart("reference counted hello world".into()); +/// +/// let y2: Yoke<&'static str, &str> = Yoke::attach_to_zero_copy_cart("borrowed hello world"); +/// +/// type CombinedYoke<'a> = Yoke<&'static str, EitherCart, &'a str>>; +/// +/// // Both yokes can be combined into a single yoke type despite different carts +/// let y3: CombinedYoke = y1.wrap_cart_in_either_a(); +/// let y4: CombinedYoke = y2.wrap_cart_in_either_b(); +/// +/// assert_eq!(*y3.get(), "reference counted hello world"); +/// assert_eq!(*y4.get(), "borrowed hello world"); +/// +/// // The resulting yoke is cloneable if both cart types implement CloneableCart +/// let y5 = y4.clone(); +/// assert_eq!(*y5.get(), "borrowed hello world"); +/// ``` +#[derive(Clone, PartialEq, Eq, Debug)] +#[allow(clippy::exhaustive_enums)] // stable +pub enum EitherCart { + A(C0), + B(C1), +} + +impl Deref for EitherCart +where + C0: Deref, + C1: Deref, +{ + type Target = T; + fn deref(&self) -> &T { + use EitherCart::*; + match self { + A(a) => a.deref(), + B(b) => b.deref(), + } + } +} + +// Safe because both sub-types implement the trait. +unsafe impl StableDeref for EitherCart +where + C0: StableDeref, + C1: StableDeref, + C0: Deref, + C1: Deref, +{ +} + +// Safe because both sub-types implement the trait. +unsafe impl CloneableCart for EitherCart +where + C0: CloneableCart, + C1: CloneableCart, +{ +} diff --git a/third_party/rust/yoke/src/erased.rs b/third_party/rust/yoke/src/erased.rs new file mode 100644 index 0000000000..4395404a66 --- /dev/null +++ b/third_party/rust/yoke/src/erased.rs @@ -0,0 +1,41 @@ +// This file is part of ICU4X. For terms of use, please see the file +// called LICENSE at the top level of the ICU4X source tree +// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ). + +//! This module contains helper types for erasing Cart types. +//! +//! See the docs of [`Yoke::erase_rc_cart()`](crate::Yoke::erase_rc_cart) +//! and [`Yoke::erase_box_cart()`](crate::Yoke::erase_box_cart) for more info. +//! +//! ✨ *Enabled with the `alloc` Cargo feature.* + +use alloc::boxed::Box; +use alloc::rc::Rc; +use alloc::sync::Arc; + +/// Dummy trait that lets us `dyn Drop` +/// +/// `dyn Drop` isn't legal (and doesn't make sense since `Drop` is not +/// implement on all destructible types). However, all trait objects come with +/// a destructor, so we can just use an empty trait to get a destructor object. +pub trait ErasedDestructor: 'static {} +impl ErasedDestructor for T {} + +/// A type-erased Cart that has `Arc` semantics +/// +/// See the docs of [`Yoke::erase_arc_cart()`](crate::Yoke::erase_rc_cart) for more info. +/// +/// ✨ *Enabled with the `alloc` Cargo feature.* +pub type ErasedArcCart = Arc; +/// A type-erased Cart that has `Rc` semantics +/// +/// See the docs of [`Yoke::erase_rc_cart()`](crate::Yoke::erase_rc_cart) for more info. +/// +/// ✨ *Enabled with the `alloc` Cargo feature.* +pub type ErasedRcCart = Rc; +/// A type-erased Cart that has `Box` semantics +/// +/// See the docs of [`Yoke::erase_box_cart()`](crate::Yoke::erase_box_cart) for more info. +/// +/// ✨ *Enabled with the `alloc` Cargo feature.* +pub type ErasedBoxCart = Box; diff --git a/third_party/rust/yoke/src/kinda_sorta_dangling.rs b/third_party/rust/yoke/src/kinda_sorta_dangling.rs new file mode 100644 index 0000000000..32e1f57097 --- /dev/null +++ b/third_party/rust/yoke/src/kinda_sorta_dangling.rs @@ -0,0 +1,94 @@ +// This file is part of ICU4X. For terms of use, please see the file +// called LICENSE at the top level of the ICU4X source tree +// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ). + +use core::mem::{ManuallyDrop, MaybeUninit}; +use core::ops::{Deref, DerefMut}; + +/// This type is intended to be similar to the type `MaybeDangling` +/// proposed in [RFC 3336]. +/// +/// The effect of this is that in Rust's safety model, types inside here are not +/// expected to have any memory dependent validity properties (`dereferenceable`, `noalias`). +/// +/// See [#3696] for a testcase where `Yoke` fails this under miri's field-retagging mode. +/// +/// This has `T: 'static` since we don't need anything +/// else and we don't want to have to think (more) about variance over lifetimes or dropck. +/// +/// After [RFC 3336] lands we can use `MaybeDangling` instead. +/// +/// Note that a version of this type also exists publicly as the [`maybe_dangling`] +/// crate; which also exports a patched `ManuallyDrop` with similar semantics and +/// does not require `T: 'static`. Consider using this if you need something more general +/// and are okay with adding dependencies. +/// +/// [RFC 3336]: https://github.com/rust-lang/rfcs/pull/3336 +/// [#3696]: https://github.com/unicode-org/icu4x/issues/3696 +/// [`maybe_dangling`](https://docs.rs/maybe-dangling/0.1.0/maybe_dangling/struct.MaybeDangling.html) +#[repr(transparent)] +pub(crate) struct KindaSortaDangling { + /// Safety invariant: This is always an initialized T, never uninit or other + /// invalid bit patterns. Its drop glue will execute during Drop::drop rather than + /// during the drop glue for KindaSortaDangling, which means that we have to be careful about + /// not touching the values as initialized during `drop` after that, but that's a short period of time. + dangle: MaybeUninit, +} + +impl KindaSortaDangling { + #[inline] + pub(crate) const fn new(dangle: T) -> Self { + KindaSortaDangling { + dangle: MaybeUninit::new(dangle), + } + } + #[inline] + pub(crate) fn into_inner(self) -> T { + // Self has a destructor, we want to avoid having it be called + let manual = ManuallyDrop::new(self); + // Safety: + // We can call assume_init_read() due to the library invariant on this type, + // however since it is a read() we must be careful about data duplication. + // The only code using `self` after this is the drop glue, which we have disabled via + // the ManuallyDrop. + unsafe { manual.dangle.assume_init_read() } + } +} + +impl Deref for KindaSortaDangling { + type Target = T; + #[inline] + fn deref(&self) -> &T { + // Safety: Safe due to the safety invariant on `dangle`; + // we can always assume initialized + unsafe { self.dangle.assume_init_ref() } + } +} + +impl DerefMut for KindaSortaDangling { + #[inline] + fn deref_mut(&mut self) -> &mut T { + // Safety: Safe due to the safety invariant on `dangle`; + // we can always assume initialized + unsafe { self.dangle.assume_init_mut() } + } +} + +impl Drop for KindaSortaDangling { + #[inline] + fn drop(&mut self) { + unsafe { + // Safety: We are reading and dropping a valid initialized T. + // + // As `drop_in_place()` is a `read()`-like duplication operation we must be careful that the original value isn't + // used afterwards. It won't be because this is drop and the only + // code that will run after this is `self`'s drop glue, and that drop glue is empty + // because MaybeUninit has no drop. + // + // We use `drop_in_place()` instead of `let _ = ... .assume_init_read()` to avoid creating a move + // of the inner `T` (without `KindaSortaDangling` protection!) type into a local -- we don't want to + // assert any of `T`'s memory-related validity properties here. + self.dangle.as_mut_ptr().drop_in_place(); + } + } +} diff --git a/third_party/rust/yoke/src/lib.rs b/third_party/rust/yoke/src/lib.rs new file mode 100644 index 0000000000..e5adca62fb --- /dev/null +++ b/third_party/rust/yoke/src/lib.rs @@ -0,0 +1,66 @@ +// This file is part of ICU4X. For terms of use, please see the file +// called LICENSE at the top level of the ICU4X source tree +// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ). + +//! This crate provides [`Yoke`][Yoke], which allows one to "yoke" (attach) a zero-copy deserialized +//! object (say, a [`Cow<'a, str>`](alloc::borrow::Cow)) to the source it was deserialized from, (say, an [`Rc<[u8]>`](alloc::rc::Rc)), +//! known in this crate as a "cart", producing a type that looks like `Yoke, Rc<[u8]>>` +//! and can be moved around with impunity. +//! +//! Succinctly, this allows one to "erase" static lifetimes and turn them into dynamic ones, similarly +//! to how `dyn` allows one to "erase" static types and turn them into dynamic ones. +//! +//! Most of the time the yokeable `Y` type will be some kind of zero-copy deserializable +//! abstraction, potentially with an owned variant (like [`Cow`](alloc::borrow::Cow), +//! [`ZeroVec`](https://docs.rs/zerovec), or an aggregate containing such types), and the cart `C` will be some smart pointer like +//! [`Box`](alloc::boxed::Box), [`Rc`](alloc::rc::Rc), or [`Arc`](std::sync::Arc), potentially wrapped in an [`Option`](Option). +//! +//! The key behind this crate is [`Yoke::get()`], where calling [`.get()`][Yoke::get] on a type like +//! `Yoke, _>` will get you a short-lived `&'a Cow<'a, str>`, restricted to the +//! lifetime of the borrow used during [`.get()`](Yoke::get). This is entirely safe since the `Cow` borrows from +//! the cart type `C`, which cannot be interfered with as long as the `Yoke` is borrowed by [`.get()`](Yoke::get). +//! [`.get()`](Yoke::get) protects access by essentially reifying the erased lifetime to a safe local one +//! when necessary. +//! +//! See the documentation of [`Yoke`] for more details. + +// https://github.com/unicode-org/icu4x/blob/main/docs/process/boilerplate.md#library-annotations +#![cfg_attr(all(not(test), not(doc)), no_std)] +#![cfg_attr( + not(test), + deny( + clippy::indexing_slicing, + clippy::unwrap_used, + clippy::expect_used, + clippy::panic, + clippy::exhaustive_structs, + clippy::exhaustive_enums, + missing_debug_implementations, + ) +)] +// The lifetimes here are important for safety and explicitly writing +// them out is good even when redundant +#![allow(clippy::needless_lifetimes)] + +#[cfg(feature = "alloc")] +extern crate alloc; + +pub mod either; +#[cfg(feature = "alloc")] +pub mod erased; +mod kinda_sorta_dangling; +mod macro_impls; +pub mod trait_hack; +mod yoke; +mod yokeable; +#[cfg(feature = "zerofrom")] +mod zero_from; + +#[cfg(feature = "derive")] +pub use yoke_derive::Yokeable; + +pub use crate::yoke::{CloneableCart, Yoke}; +pub use crate::yokeable::Yokeable; + +#[cfg(feature = "zerofrom")] +use zerofrom::ZeroFrom; diff --git a/third_party/rust/yoke/src/macro_impls.rs b/third_party/rust/yoke/src/macro_impls.rs new file mode 100644 index 0000000000..060061b209 --- /dev/null +++ b/third_party/rust/yoke/src/macro_impls.rs @@ -0,0 +1,108 @@ +// This file is part of ICU4X. For terms of use, please see the file +// called LICENSE at the top level of the ICU4X source tree +// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ). + +// In this case consistency between impls is more important +// than using pointer casts +#![allow(clippy::transmute_ptr_to_ptr)] + +use crate::Yokeable; +use core::{mem, ptr}; + +macro_rules! copy_yoke_impl { + () => { + #[inline] + fn transform(&self) -> &Self::Output { + self + } + #[inline] + fn transform_owned(self) -> Self::Output { + self + } + #[inline] + unsafe fn make(this: Self::Output) -> Self { + this + } + #[inline] + fn transform_mut(&'a mut self, f: F) + where + F: 'static + for<'b> FnOnce(&'b mut Self::Output), + { + f(self) + } + }; +} +macro_rules! impl_copy_type { + ($ty:ident) => { + unsafe impl<'a> Yokeable<'a> for $ty { + type Output = Self; + copy_yoke_impl!(); + } + }; +} + +impl_copy_type!(u8); +impl_copy_type!(u16); +impl_copy_type!(u32); +impl_copy_type!(u64); +impl_copy_type!(u128); +impl_copy_type!(usize); +impl_copy_type!(i8); +impl_copy_type!(i16); +impl_copy_type!(i32); +impl_copy_type!(i64); +impl_copy_type!(i128); +impl_copy_type!(isize); +impl_copy_type!(char); +impl_copy_type!(bool); + +// This is for when we're implementing Yoke on a complex type such that it's not +// obvious to the compiler that the lifetime is covariant +macro_rules! unsafe_complex_yoke_impl { + () => { + fn transform(&'a self) -> &'a Self::Output { + unsafe { mem::transmute(self) } + } + + fn transform_owned(self) -> Self::Output { + debug_assert!(mem::size_of::() == mem::size_of::()); + unsafe { + let ptr: *const Self::Output = (&self as *const Self).cast(); + mem::forget(self); + ptr::read(ptr) + } + } + + unsafe fn make(from: Self::Output) -> Self { + debug_assert!(mem::size_of::() == mem::size_of::()); + let ptr: *const Self = (&from as *const Self::Output).cast(); + mem::forget(from); + ptr::read(ptr) + } + + fn transform_mut(&'a mut self, f: F) + where + F: 'static + for<'b> FnOnce(&'b mut Self::Output), + { + // Cast away the lifetime of Self + unsafe { f(mem::transmute::<&'a mut Self, &'a mut Self::Output>(self)) } + } + }; +} + +unsafe impl<'a, T: 'static + for<'b> Yokeable<'b>> Yokeable<'a> for Option { + type Output = Option<>::Output>; + unsafe_complex_yoke_impl!(); +} + +unsafe impl<'a, T1: 'static + for<'b> Yokeable<'b>, T2: 'static + for<'b> Yokeable<'b>> Yokeable<'a> + for (T1, T2) +{ + type Output = (>::Output, >::Output); + unsafe_complex_yoke_impl!(); +} + +unsafe impl<'a, T: Yokeable<'a>, const N: usize> Yokeable<'a> for [T; N] { + type Output = [>::Output; N]; + unsafe_complex_yoke_impl!(); +} diff --git a/third_party/rust/yoke/src/trait_hack.rs b/third_party/rust/yoke/src/trait_hack.rs new file mode 100644 index 0000000000..f3ffaee2ba --- /dev/null +++ b/third_party/rust/yoke/src/trait_hack.rs @@ -0,0 +1,318 @@ +// This file is part of ICU4X. For terms of use, please see the file +// called LICENSE at the top level of the ICU4X source tree +// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ). + +//! Workarounds for adding trait bounds to `yoke` objects. +//! +//! # Trait bounds in Yoke +//! +//! [Compiler bug #89196](https://github.com/rust-lang/rust/issues/89196) makes it tricky to add +//! trait bounds involving `yoke` types. +//! +//! For example, you may want to write: +//! +//! `where for<'a> >::Output: MyTrait` +//! +//! The above trait bound will compile, but at call sites, you get errors such as: +//! +//! > the trait `for<'de> MyTrait` is not implemented for `>::Output` +//! +//! There are two known workarounds: +//! +//! 1. If the trait is well-defined on references, like `Debug`, bind the trait to a reference: +//! `where for<'a> &'a >::Output: MyTrait` +//! 2. If the trait involves `Self`, like `Clone`, use [`YokeTraitHack`]: +//! `where for<'a> YokeTraitHack<>::Output>: MyTrait` +//! +//! # Examples +//! +//! Code that does not compile ([playground](https://play.rust-lang.org/?version=beta&mode=debug&edition=2018&gist=ebbda5b15a398d648bdff9e439b27dc0)): +//! +//! ```compile_fail +//! use yoke::*; +//! +//! trait MiniDataMarker { +//! type Yokeable: for<'a> Yokeable<'a>; +//! } +//! +//! struct MiniDataPayload +//! where +//! M: MiniDataMarker +//! { +//! pub yoke: Yoke, +//! } +//! +//! impl Clone for MiniDataPayload +//! where +//! M: MiniDataMarker, +//! for<'a> >::Output: Clone, +//! { +//! fn clone(&self) -> Self { +//! unimplemented!() +//! } +//! } +//! +//! trait MiniDataProvider +//! where +//! M: MiniDataMarker +//! { +//! fn mini_load_data(&self) -> MiniDataPayload; +//! } +//! +//! struct MiniStructProvider +//! where +//! M: MiniDataMarker, +//! { +//! pub payload: MiniDataPayload, +//! } +//! +//! impl MiniDataProvider for MiniStructProvider +//! where +//! M: MiniDataMarker, +//! for<'a> >::Output: Clone, +//! { +//! fn mini_load_data(&self) -> MiniDataPayload { +//! self.payload.clone() +//! } +//! } +//! +//! #[derive(Clone)] +//! struct SimpleStruct(pub u32); +//! +//! unsafe impl<'a> Yokeable<'a> for SimpleStruct { +//! // (not shown; see `Yokeable` for examples) +//! # type Output = SimpleStruct; +//! # fn transform(&'a self) -> &'a Self::Output { +//! # self +//! # } +//! # fn transform_owned(self) -> Self::Output { +//! # self +//! # } +//! # unsafe fn make(from: Self::Output) -> Self { +//! # std::mem::transmute(from) +//! # } +//! # fn transform_mut(&'a mut self, f: F) +//! # where +//! # F: 'static + for<'b> FnOnce(&'b mut Self::Output), +//! # { +//! # unsafe { +//! # f(std::mem::transmute::<&'a mut Self, &'a mut Self::Output>( +//! # self, +//! # )) +//! # } +//! # } +//! } +//! +//! impl MiniDataMarker for SimpleStruct { +//! type Yokeable = SimpleStruct; +//! } +//! +//! let provider = MiniStructProvider { +//! payload: MiniDataPayload { +//! yoke: Yoke::new_always_owned(SimpleStruct(42)) +//! } +//! }; +//! +//! // Broken: +//! // "method cannot be called on `MiniStructProvider<_>` due to unsatisfied trait bounds" +//! let payload: MiniDataPayload = provider.mini_load_data(); +//! +//! // Working: +//! let payload = MiniDataProvider::::mini_load_data(&provider); +//! +//! assert_eq!(payload.yoke.get().0, 42); +//! ``` +//! +//! Example for binding the trait to a reference: +//! +//! ``` +//! use yoke::Yoke; +//! use yoke::Yokeable; +//! +//! // Example trait and struct for illustration purposes: +//! trait MyTrait { +//! fn demo(&self) -> u32; +//! } +//! struct MyStruct(u32); +//! impl MyTrait for MyStruct { +//! fn demo(&self) -> u32 { +//! self.0 +//! } +//! } +//! unsafe impl<'a> Yokeable<'a> for MyStruct { +//! // (not shown; see `Yokeable` for examples) +//! # type Output = MyStruct; +//! # fn transform(&'a self) -> &'a Self::Output { +//! # self +//! # } +//! # fn transform_owned(self) -> Self::Output { +//! # self +//! # } +//! # unsafe fn make(from: Self::Output) -> Self { +//! # std::mem::transmute(from) +//! # } +//! # fn transform_mut(&'a mut self, f: F) +//! # where +//! # F: 'static + for<'b> FnOnce(&'b mut Self::Output), +//! # { +//! # unsafe { +//! # f(std::mem::transmute::<&'a mut Self, &'a mut Self::Output>( +//! # self, +//! # )) +//! # } +//! # } +//! } +//! +//! // The trait needs to be defined on references: +//! impl<'a, T> MyTrait for &'a T +//! where +//! T: MyTrait, +//! { +//! fn demo(&self) -> u32 { +//! self.demo() +//! } +//! } +//! +//! impl MyTrait for Yoke +//! where +//! Y: for<'a> Yokeable<'a>, +//! for<'a> &'a >::Output: MyTrait, +//! { +//! fn demo(&self) -> u32 { +//! self.get().demo() +//! } +//! } +//! +//! fn example() { +//! let y = Yoke::::new_always_owned(MyStruct(42)); +//! let _: &dyn MyTrait = &y; +//! } +//! ``` +//! +//! Example for using [`YokeTraitHack`]: +//! +//! ``` +//! use std::rc::Rc; +//! use yoke::trait_hack::YokeTraitHack; +//! use yoke::Yoke; +//! use yoke::Yokeable; +//! +//! // Example trait and struct for illustration purposes: +//! trait MyTrait { +//! fn demo(data: u32) -> Self; +//! } +//! struct MyStruct(u32); +//! impl MyTrait for MyStruct { +//! fn demo(data: u32) -> Self { +//! Self(data) +//! } +//! } +//! unsafe impl<'a> Yokeable<'a> for MyStruct { +//! // (not shown; see `Yokeable` for examples) +//! # type Output = MyStruct; +//! # fn transform(&'a self) -> &'a Self::Output { +//! # self +//! # } +//! # fn transform_owned(self) -> Self::Output { +//! # self +//! # } +//! # unsafe fn make(from: Self::Output) -> Self { +//! # std::mem::transmute(from) +//! # } +//! # fn transform_mut(&'a mut self, f: F) +//! # where +//! # F: 'static + for<'b> FnOnce(&'b mut Self::Output), +//! # { +//! # unsafe { +//! # f(std::mem::transmute::<&'a mut Self, &'a mut Self::Output>( +//! # self, +//! # )) +//! # } +//! # } +//! } +//! +//! // The trait needs to be defined on YokeTraitHack: +//! impl<'a, T> MyTrait for YokeTraitHack +//! where +//! T: MyTrait, +//! { +//! fn demo(data: u32) -> Self { +//! YokeTraitHack(T::demo(data)) +//! } +//! } +//! +//! impl MyTrait for Yoke> +//! where +//! Y: for<'a> Yokeable<'a>, +//! for<'a> YokeTraitHack<>::Output>: MyTrait, +//! { +//! fn demo(data: u32) -> Self { +//! let rc_u32: Rc = Rc::new(data); +//! Yoke::attach_to_cart(rc_u32, |u| { +//! YokeTraitHack::<::Output>::demo(*u).0 +//! }) +//! } +//! } +//! +//! fn example() { +//! let _ = Yoke::>::demo(42); +//! } +//! ``` + +use core::mem; + +/// A wrapper around a type `T`, forwarding trait calls down to the inner type. +/// +/// `YokeTraitHack` supports [`Clone`], [`PartialEq`], [`Eq`], and [`serde::Deserialize`] out of +/// the box. Other traits can be implemented by the caller. +/// +/// For more information, see the module-level documentation. +/// +/// # Example +/// +/// Using `YokeTraitHack` as a type bound in a function comparing two `Yoke`s: +/// +/// ``` +/// use yoke::trait_hack::YokeTraitHack; +/// use yoke::*; +/// +/// fn compare_yokes(y1: Yoke, y2: Yoke) -> bool +/// where +/// Y: for<'a> Yokeable<'a>, +/// for<'a> YokeTraitHack<>::Output>: PartialEq, +/// { +/// YokeTraitHack(y1.get()).into_ref() == YokeTraitHack(y2.get()).into_ref() +/// } +/// ``` +#[repr(transparent)] +#[derive(Clone, PartialEq, Eq, Debug)] +#[allow(clippy::exhaustive_structs)] // newtype +pub struct YokeTraitHack(pub T); + +impl<'a, T> YokeTraitHack<&'a T> { + /// Converts from `YokeTraitHack<&T>` to `&YokeTraitHack`. + /// + /// This is safe because `YokeTraitHack` is `repr(transparent)`. + /// + /// This method is required to implement `Clone` on `Yoke`. + pub fn into_ref(self) -> &'a YokeTraitHack { + // YokeTraitHack is repr(transparent) so it's always safe + // to transmute YTH<&T> to &YTH + unsafe { mem::transmute::, &YokeTraitHack>(self) } + } +} + +// This is implemented manually to avoid the serde derive dependency. +#[cfg(feature = "serde")] +impl<'de, T> serde::de::Deserialize<'de> for YokeTraitHack +where + T: serde::de::Deserialize<'de>, +{ + #[inline] + fn deserialize(deserializer: D) -> Result + where + D: serde::de::Deserializer<'de>, + { + T::deserialize(deserializer).map(YokeTraitHack) + } +} diff --git a/third_party/rust/yoke/src/yoke.rs b/third_party/rust/yoke/src/yoke.rs new file mode 100644 index 0000000000..22f14d3dc1 --- /dev/null +++ b/third_party/rust/yoke/src/yoke.rs @@ -0,0 +1,1351 @@ +// This file is part of ICU4X. For terms of use, please see the file +// called LICENSE at the top level of the ICU4X source tree +// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ). + +use crate::either::EitherCart; +#[cfg(feature = "alloc")] +use crate::erased::{ErasedArcCart, ErasedBoxCart, ErasedRcCart}; +use crate::kinda_sorta_dangling::KindaSortaDangling; +use crate::trait_hack::YokeTraitHack; +use crate::Yokeable; +use core::marker::PhantomData; +use core::ops::Deref; +use stable_deref_trait::StableDeref; + +#[cfg(feature = "alloc")] +use alloc::boxed::Box; +#[cfg(feature = "alloc")] +use alloc::rc::Rc; +#[cfg(feature = "alloc")] +use alloc::sync::Arc; + +/// A Cow-like borrowed object "yoked" to its backing data. +/// +/// This allows things like zero copy deserialized data to carry around +/// shared references to their backing buffer, by "erasing" their static lifetime +/// and turning it into a dynamically managed one. +/// +/// `Y` (the [`Yokeable`]) is the object containing the references, +/// and will typically be of the form `Foo<'static>`. The `'static` is +/// not the actual lifetime of the data, rather it is a convenient way to mark the +/// erased lifetime and make it dynamic. +/// +/// `C` is the "cart", which `Y` may contain references to. After the yoke is constructed, +/// the cart serves little purpose except to guarantee that `Y`'s references remain valid +/// for as long as the yoke remains in memory (by calling the destructor at the appropriate moment). +/// +/// The primary constructor for [`Yoke`] is [`Yoke::attach_to_cart()`]. Several variants of that +/// constructor are provided to serve numerous types of call sites and `Yoke` signatures. +/// +/// The key behind this type is [`Yoke::get()`], where calling [`.get()`][Yoke::get] on a type like +/// `Yoke, _>` will get you a short-lived `&'a Cow<'a, str>`, restricted to the +/// lifetime of the borrow used during `.get()`. This is entirely safe since the `Cow` borrows from +/// the cart type `C`, which cannot be interfered with as long as the `Yoke` is borrowed by `.get +/// ()`. `.get()` protects access by essentially reifying the erased lifetime to a safe local one +/// when necessary. +/// +/// Furthermore, there are various [`.map_project()`][Yoke::map_project] methods that allow turning a `Yoke` +/// into another `Yoke` containing a different type that may contain elements of the original yoked +/// value. See the [`Yoke::map_project()`] docs for more details. +/// +/// In general, `C` is a concrete type, but it is also possible for it to be a trait object. +/// +/// # Example +/// +/// For example, we can use this to store zero-copy deserialized data in a cache: +/// +/// ```rust +/// # use yoke::{Yoke, Yokeable}; +/// # use std::rc::Rc; +/// # use std::borrow::Cow; +/// # fn load_from_cache(_filename: &str) -> Rc<[u8]> { +/// # // dummy implementation +/// # Rc::new([0x5, 0, 0, 0, 0, 0, 0, 0, 0x68, 0x65, 0x6c, 0x6c, 0x6f]) +/// # } +/// +/// fn load_object(filename: &str) -> Yoke, Rc<[u8]>> { +/// let rc: Rc<[u8]> = load_from_cache(filename); +/// Yoke::, Rc<[u8]>>::attach_to_cart(rc, |data: &[u8]| { +/// // essentially forcing a #[serde(borrow)] +/// Cow::Borrowed(bincode::deserialize(data).unwrap()) +/// }) +/// } +/// +/// let yoke = load_object("filename.bincode"); +/// assert_eq!(&**yoke.get(), "hello"); +/// assert!(matches!(yoke.get(), &Cow::Borrowed(_))); +/// ``` +pub struct Yoke Yokeable<'a>, C> { + // must be the first field for drop order + // this will have a 'static lifetime parameter, that parameter is a lie + yokeable: KindaSortaDangling, + cart: C, +} + +// Manual `Debug` implementation, since the derived one would be unsound. +// See https://github.com/unicode-org/icu4x/issues/3685 +impl Yokeable<'a>, C: core::fmt::Debug> core::fmt::Debug for Yoke +where + for<'a> >::Output: core::fmt::Debug, +{ + fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { + f.debug_struct("Yoke") + .field("yokeable", self.get()) + .field("cart", self.backing_cart()) + .finish() + } +} + +#[test] +fn test_debug() { + let local_data = "foo".to_owned(); + let y1 = Yoke::, Rc>::attach_to_zero_copy_cart( + Rc::new(local_data), + ); + assert_eq!( + format!("{y1:?}"), + r#"Yoke { yokeable: "foo", cart: "foo" }"#, + ); +} + +impl Yokeable<'a>, C: StableDeref> Yoke +where + ::Target: 'static, +{ + /// Construct a [`Yoke`] by yokeing an object to a cart in a closure. + /// + /// See also [`Yoke::try_attach_to_cart()`] to return a `Result` from the closure. + /// + /// Call sites for this function may not compile pre-1.61; if this still happens, use + /// [`Yoke::attach_to_cart_badly()`] and file a bug. + /// + /// # Examples + /// + /// ``` + /// # use yoke::{Yoke, Yokeable}; + /// # use std::rc::Rc; + /// # use std::borrow::Cow; + /// # fn load_from_cache(_filename: &str) -> Rc<[u8]> { + /// # // dummy implementation + /// # Rc::new([0x5, 0, 0, 0, 0, 0, 0, 0, 0x68, 0x65, 0x6c, 0x6c, 0x6f]) + /// # } + /// + /// fn load_object(filename: &str) -> Yoke, Rc<[u8]>> { + /// let rc: Rc<[u8]> = load_from_cache(filename); + /// Yoke::, Rc<[u8]>>::attach_to_cart(rc, |data: &[u8]| { + /// // essentially forcing a #[serde(borrow)] + /// Cow::Borrowed(bincode::deserialize(data).unwrap()) + /// }) + /// } + /// + /// let yoke: Yoke, _> = load_object("filename.bincode"); + /// assert_eq!(&**yoke.get(), "hello"); + /// assert!(matches!(yoke.get(), &Cow::Borrowed(_))); + /// ``` + pub fn attach_to_cart(cart: C, f: F) -> Self + where + // safety note: This works by enforcing that the *only* place the return value of F + // can borrow from is the cart, since `F` must be valid for all lifetimes `'de` + // + // The ::Target: 'static on the impl is crucial for safety as well + // + // See safety docs at the bottom of this file for more information + F: for<'de> FnOnce(&'de ::Target) -> >::Output, + ::Target: 'static, + { + let deserialized = f(cart.deref()); + Self { + yokeable: KindaSortaDangling::new(unsafe { Y::make(deserialized) }), + cart, + } + } + + /// Construct a [`Yoke`] by yokeing an object to a cart. If an error occurs in the + /// deserializer function, the error is passed up to the caller. + /// + /// Call sites for this function may not compile pre-1.61; if this still happens, use + /// [`Yoke::try_attach_to_cart_badly()`] and file a bug. + pub fn try_attach_to_cart(cart: C, f: F) -> Result + where + F: for<'de> FnOnce(&'de ::Target) -> Result<>::Output, E>, + { + let deserialized = f(cart.deref())?; + Ok(Self { + yokeable: KindaSortaDangling::new(unsafe { Y::make(deserialized) }), + cart, + }) + } + + /// Use [`Yoke::attach_to_cart()`]. + /// + /// This was needed because the pre-1.61 compiler couldn't always handle the FnOnce trait bound. + #[deprecated] + pub fn attach_to_cart_badly( + cart: C, + f: for<'de> fn(&'de ::Target) -> >::Output, + ) -> Self { + Self::attach_to_cart(cart, f) + } + + /// Use [`Yoke::try_attach_to_cart()`]. + /// + /// This was needed because the pre-1.61 compiler couldn't always handle the FnOnce trait bound. + #[deprecated] + pub fn try_attach_to_cart_badly( + cart: C, + f: for<'de> fn(&'de ::Target) -> Result<>::Output, E>, + ) -> Result { + Self::try_attach_to_cart(cart, f) + } +} + +impl Yokeable<'a>, C> Yoke { + /// Obtain a valid reference to the yokeable data + /// + /// This essentially transforms the lifetime of the internal yokeable data to + /// be valid. + /// For example, if you're working with a `Yoke, C>`, this + /// will return an `&'a Cow<'a, T>` + /// + /// # Example + /// + /// ```rust + /// # use yoke::{Yoke, Yokeable}; + /// # use std::rc::Rc; + /// # use std::borrow::Cow; + /// # fn load_from_cache(_filename: &str) -> Rc<[u8]> { + /// # // dummy implementation + /// # Rc::new([0x5, 0, 0, 0, 0, 0, 0, 0, 0x68, 0x65, 0x6c, 0x6c, 0x6f]) + /// # } + /// # + /// # fn load_object(filename: &str) -> Yoke, Rc<[u8]>> { + /// # let rc: Rc<[u8]> = load_from_cache(filename); + /// # Yoke::, Rc<[u8]>>::attach_to_cart(rc, |data: &[u8]| { + /// # Cow::Borrowed(bincode::deserialize(data).unwrap()) + /// # }) + /// # } + /// + /// // load_object() defined in the example at the top of this page + /// let yoke: Yoke, _> = load_object("filename.bincode"); + /// assert_eq!(yoke.get(), "hello"); + /// ``` + #[inline] + pub fn get<'a>(&'a self) -> &'a >::Output { + self.yokeable.transform() + } + + /// Get a reference to the backing cart. + /// + /// This can be useful when building caches, etc. However, if you plan to store the cart + /// separately from the yoke, read the note of caution below in [`Yoke::into_backing_cart`]. + pub fn backing_cart(&self) -> &C { + &self.cart + } + + /// Get the backing cart by value, dropping the yokeable object. + /// + /// **Caution:** Calling this method could cause information saved in the yokeable object but + /// not the cart to be lost. Use this method only if the yokeable object cannot contain its + /// own information. + /// + /// # Example + /// + /// Good example: the yokeable object is only a reference, so no information can be lost. + /// + /// ``` + /// use yoke::Yoke; + /// + /// let local_data = "foo".to_owned(); + /// let yoke = Yoke::<&'static str, Box>::attach_to_zero_copy_cart( + /// Box::new(local_data), + /// ); + /// assert_eq!(*yoke.get(), "foo"); + /// + /// // Get back the cart + /// let cart = yoke.into_backing_cart(); + /// assert_eq!(&*cart, "foo"); + /// ``` + /// + /// Bad example: information specified in `.with_mut()` is lost. + /// + /// ``` + /// use std::borrow::Cow; + /// use yoke::Yoke; + /// + /// let local_data = "foo".to_owned(); + /// let mut yoke = + /// Yoke::, Box>::attach_to_zero_copy_cart( + /// Box::new(local_data), + /// ); + /// assert_eq!(yoke.get(), "foo"); + /// + /// // Override data in the cart + /// yoke.with_mut(|cow| { + /// let mut_str = cow.to_mut(); + /// mut_str.clear(); + /// mut_str.push_str("bar"); + /// }); + /// assert_eq!(yoke.get(), "bar"); + /// + /// // Get back the cart + /// let cart = yoke.into_backing_cart(); + /// assert_eq!(&*cart, "foo"); // WHOOPS! + /// ``` + pub fn into_backing_cart(self) -> C { + self.cart + } + + /// Unsafe function for replacing the cart with another + /// + /// This can be used for type-erasing the cart, for example. + /// + /// # Safety + /// + /// - `f()` must not panic + /// - References from the yokeable `Y` should still be valid for the lifetime of the + /// returned cart type `C`. + /// - Lifetimes inside C must not be lengthened, even if they are themselves contravariant. + /// I.e., if C contains an `fn(&'a u8)`, it cannot be replaced with `fn(&'static u8), + /// even though that is typically safe. + /// + /// Typically, this means implementing `f` as something which _wraps_ the inner cart type `C`. + /// `Yoke` only really cares about destructors for its carts so it's fine to erase other + /// information about the cart, as long as the backing data will still be destroyed at the + /// same time. + #[inline] + pub unsafe fn replace_cart(self, f: impl FnOnce(C) -> C2) -> Yoke { + Yoke { + yokeable: self.yokeable, + cart: f(self.cart), + } + } + + /// Mutate the stored [`Yokeable`] data. + /// + /// See [`Yokeable::transform_mut()`] for why this operation is safe. + /// + /// # Example + /// + /// This can be used to partially mutate the stored data, provided + /// no _new_ borrowed data is introduced. + /// + /// ```rust + /// # use yoke::{Yoke, Yokeable}; + /// # use std::rc::Rc; + /// # use std::borrow::Cow; + /// # use std::mem; + /// # fn load_from_cache(_filename: &str) -> Rc<[u8]> { + /// # // dummy implementation + /// # Rc::new([0x5, 0, 0, 0, 0, 0, 0, 0, 0x68, 0x65, 0x6c, 0x6c, 0x6f]) + /// # } + /// # + /// # fn load_object(filename: &str) -> Yoke, Rc<[u8]>> { + /// # let rc: Rc<[u8]> = load_from_cache(filename); + /// # Yoke::, Rc<[u8]>>::attach_to_cart(rc, |data: &[u8]| { + /// # // A real implementation would properly deserialize `Bar` as a whole + /// # Bar { + /// # numbers: Cow::Borrowed(bincode::deserialize(data).unwrap()), + /// # string: Cow::Borrowed(bincode::deserialize(data).unwrap()), + /// # owned: Vec::new(), + /// # } + /// # }) + /// # } + /// + /// // also implements Yokeable + /// struct Bar<'a> { + /// numbers: Cow<'a, [u8]>, + /// string: Cow<'a, str>, + /// owned: Vec, + /// } + /// + /// // `load_object()` deserializes an object from a file + /// let mut bar: Yoke = load_object("filename.bincode"); + /// assert_eq!(bar.get().string, "hello"); + /// assert!(matches!(bar.get().string, Cow::Borrowed(_))); + /// assert_eq!(&*bar.get().numbers, &[0x68, 0x65, 0x6c, 0x6c, 0x6f]); + /// assert!(matches!(bar.get().numbers, Cow::Borrowed(_))); + /// assert_eq!(&*bar.get().owned, &[]); + /// + /// bar.with_mut(|bar| { + /// bar.string.to_mut().push_str(" world"); + /// bar.owned.extend_from_slice(&[1, 4, 1, 5, 9]); + /// }); + /// + /// assert_eq!(bar.get().string, "hello world"); + /// assert!(matches!(bar.get().string, Cow::Owned(_))); + /// assert_eq!(&*bar.get().owned, &[1, 4, 1, 5, 9]); + /// // Unchanged and still Cow::Borrowed + /// assert_eq!(&*bar.get().numbers, &[0x68, 0x65, 0x6c, 0x6c, 0x6f]); + /// assert!(matches!(bar.get().numbers, Cow::Borrowed(_))); + /// + /// # unsafe impl<'a> Yokeable<'a> for Bar<'static> { + /// # type Output = Bar<'a>; + /// # fn transform(&'a self) -> &'a Bar<'a> { + /// # self + /// # } + /// # + /// # fn transform_owned(self) -> Bar<'a> { + /// # // covariant lifetime cast, can be done safely + /// # self + /// # } + /// # + /// # unsafe fn make(from: Bar<'a>) -> Self { + /// # let ret = mem::transmute_copy(&from); + /// # mem::forget(from); + /// # ret + /// # } + /// # + /// # fn transform_mut(&'a mut self, f: F) + /// # where + /// # F: 'static + FnOnce(&'a mut Self::Output), + /// # { + /// # unsafe { f(mem::transmute(self)) } + /// # } + /// # } + /// ``` + pub fn with_mut<'a, F>(&'a mut self, f: F) + where + F: 'static + for<'b> FnOnce(&'b mut >::Output), + { + self.yokeable.transform_mut(f) + } + + /// Helper function allowing one to wrap the cart type `C` in an `Option`. + #[inline] + pub fn wrap_cart_in_option(self) -> Yoke> { + unsafe { + // safe because the cart is preserved, just wrapped + self.replace_cart(Some) + } + } +} + +impl Yokeable<'a>> Yoke { + /// Construct a new [`Yoke`] from static data. There will be no + /// references to `cart` here since [`Yokeable`]s are `'static`, + /// this is good for e.g. constructing fully owned + /// [`Yoke`]s with no internal borrowing. + /// + /// This is similar to [`Yoke::new_owned()`] but it does not allow you to + /// mix the [`Yoke`] with borrowed data. This is primarily useful + /// for using [`Yoke`] in generic scenarios. + /// + /// # Example + /// + /// ```rust + /// # use yoke::Yoke; + /// # use std::borrow::Cow; + /// # use std::rc::Rc; + /// + /// let owned: Cow = "hello".to_owned().into(); + /// // this yoke can be intermingled with actually-borrowed Yokes + /// let yoke: Yoke, ()> = Yoke::new_always_owned(owned); + /// + /// assert_eq!(yoke.get(), "hello"); + /// ``` + pub fn new_always_owned(yokeable: Y) -> Self { + Self { + yokeable: KindaSortaDangling::new(yokeable), + cart: (), + } + } + + /// Obtain the yokeable out of a `Yoke` + /// + /// For most `Yoke` types this would be unsafe but it's + /// fine for `Yoke` since there are no actual internal + /// references + pub fn into_yokeable(self) -> Y { + self.yokeable.into_inner() + } +} + +impl Yokeable<'a>, C: StableDeref> Yoke> { + /// Construct a new [`Yoke`] from static data. There will be no + /// references to `cart` here since [`Yokeable`]s are `'static`, + /// this is good for e.g. constructing fully owned + /// [`Yoke`]s with no internal borrowing. + /// + /// This can be paired with [`Yoke:: wrap_cart_in_option()`] to mix owned + /// and borrowed data. + /// + /// If you do not wish to pair this with borrowed data, [`Yoke::new_always_owned()`] can + /// be used to get a [`Yoke`] API on always-owned data. + /// + /// # Example + /// + /// ```rust + /// # use yoke::Yoke; + /// # use std::borrow::Cow; + /// # use std::rc::Rc; + /// + /// let owned: Cow = "hello".to_owned().into(); + /// // this yoke can be intermingled with actually-borrowed Yokes + /// let yoke: Yoke, Option>> = Yoke::new_owned(owned); + /// + /// assert_eq!(yoke.get(), "hello"); + /// ``` + pub const fn new_owned(yokeable: Y) -> Self { + Self { + yokeable: KindaSortaDangling::new(yokeable), + cart: None, + } + } + + /// Obtain the yokeable out of a `Yoke>` if possible. + /// + /// If the cart is `None`, this returns `Some`, but if the cart is `Some`, + /// this returns `self` as an error. + pub fn try_into_yokeable(self) -> Result { + match self.cart { + Some(_) => Err(self), + None => Ok(self.yokeable.into_inner()), + } + } +} + +/// This trait marks cart types that do not change source on cloning +/// +/// This is conceptually similar to [`stable_deref_trait::CloneStableDeref`], +/// however [`stable_deref_trait::CloneStableDeref`] is not (and should not) be +/// implemented on [`Option`] (since it's not [`Deref`]). [`CloneableCart`] essentially is +/// "if there _is_ data to borrow from here, cloning the cart gives you an additional +/// handle to the same data". +/// +/// # Safety +/// This trait is safe to implement `StableDeref` types which, once `Clone`d, point to the same underlying data. +/// +/// (This trait is also implemented on `Option` and `()`, which are the two non-`StableDeref` cart types that +/// Yokes can be constructed for) +pub unsafe trait CloneableCart: Clone {} + +#[cfg(feature = "alloc")] +unsafe impl CloneableCart for Rc {} +#[cfg(feature = "alloc")] +unsafe impl CloneableCart for Arc {} +unsafe impl CloneableCart for Option {} +unsafe impl<'a, T: ?Sized> CloneableCart for &'a T {} +unsafe impl CloneableCart for () {} + +/// Clone requires that the cart type `C` derefs to the same address after it is cloned. This works for +/// Rc, Arc, and &'a T. +/// +/// For other cart types, clone `.backing_cart()` and re-use `.attach_to_cart()`; however, doing +/// so may lose mutations performed via `.with_mut()`. +/// +/// Cloning a `Yoke` is often a cheap operation requiring no heap allocations, in much the same +/// way that cloning an `Rc` is a cheap operation. However, if the `yokeable` contains owned data +/// (e.g., from `.with_mut()`), that data will need to be cloned. +impl Yokeable<'a>, C: CloneableCart> Clone for Yoke +where + for<'a> YokeTraitHack<>::Output>: Clone, +{ + fn clone(&self) -> Self { + let this: &Y::Output = self.get(); + // We have an &T not a T, and we can clone YokeTraitHack + let this_hack = YokeTraitHack(this).into_ref(); + Yoke { + yokeable: KindaSortaDangling::new(unsafe { Y::make(this_hack.clone().0) }), + cart: self.cart.clone(), + } + } +} + +#[test] +fn test_clone() { + let local_data = "foo".to_owned(); + let y1 = Yoke::, Rc>::attach_to_zero_copy_cart( + Rc::new(local_data), + ); + + // Test basic clone + let y2 = y1.clone(); + assert_eq!(y1.get(), "foo"); + assert_eq!(y2.get(), "foo"); + + // Test clone with mutation on target + let mut y3 = y1.clone(); + y3.with_mut(|y| { + y.to_mut().push_str("bar"); + }); + assert_eq!(y1.get(), "foo"); + assert_eq!(y2.get(), "foo"); + assert_eq!(y3.get(), "foobar"); + + // Test that mutations on source do not affect target + let y4 = y3.clone(); + y3.with_mut(|y| { + y.to_mut().push_str("baz"); + }); + assert_eq!(y1.get(), "foo"); + assert_eq!(y2.get(), "foo"); + assert_eq!(y3.get(), "foobarbaz"); + assert_eq!(y4.get(), "foobar"); +} + +impl Yokeable<'a>, C> Yoke { + /// Allows one to "project" a yoke to perform a transformation on the data, potentially + /// looking at a subfield, and producing a new yoke. This will move cart, and the provided + /// transformation is only allowed to use data known to be borrowed from the cart. + /// + /// The callback takes an additional `PhantomData<&()>` parameter to anchor lifetimes + /// (see [#86702](https://github.com/rust-lang/rust/issues/86702)) This parameter + /// should just be ignored in the callback. + /// + /// This can be used, for example, to transform data from one format to another: + /// + /// ``` + /// # use std::rc::Rc; + /// # use yoke::Yoke; + /// # + /// fn slice(y: Yoke<&'static str, Rc<[u8]>>) -> Yoke<&'static [u8], Rc<[u8]>> { + /// y.map_project(move |yk, _| yk.as_bytes()) + /// } + /// ``` + /// + /// This can also be used to create a yoke for a subfield + /// + /// ``` + /// # use std::borrow::Cow; + /// # use yoke::{Yoke, Yokeable}; + /// # use std::mem; + /// # use std::rc::Rc; + /// # + /// // also safely implements Yokeable<'a> + /// struct Bar<'a> { + /// string_1: &'a str, + /// string_2: &'a str, + /// } + /// + /// fn map_project_string_1( + /// bar: Yoke, Rc<[u8]>>, + /// ) -> Yoke<&'static str, Rc<[u8]>> { + /// bar.map_project(|bar, _| bar.string_1) + /// } + /// + /// # + /// # unsafe impl<'a> Yokeable<'a> for Bar<'static> { + /// # type Output = Bar<'a>; + /// # fn transform(&'a self) -> &'a Bar<'a> { + /// # self + /// # } + /// # + /// # fn transform_owned(self) -> Bar<'a> { + /// # // covariant lifetime cast, can be done safely + /// # self + /// # } + /// # + /// # unsafe fn make(from: Bar<'a>) -> Self { + /// # let ret = mem::transmute_copy(&from); + /// # mem::forget(from); + /// # ret + /// # } + /// # + /// # fn transform_mut(&'a mut self, f: F) + /// # where + /// # F: 'static + FnOnce(&'a mut Self::Output), + /// # { + /// # unsafe { f(mem::transmute(self)) } + /// # } + /// # } + /// ``` + // + // Safety docs can be found below on `__project_safety_docs()` + pub fn map_project(self, f: F) -> Yoke + where + P: for<'a> Yokeable<'a>, + F: for<'a> FnOnce( + >::Output, + PhantomData<&'a ()>, + ) ->

>::Output, + { + let p = f(self.yokeable.into_inner().transform_owned(), PhantomData); + Yoke { + yokeable: KindaSortaDangling::new(unsafe { P::make(p) }), + cart: self.cart, + } + } + + /// This is similar to [`Yoke::map_project`], however it does not move + /// [`Self`] and instead clones the cart (only if the cart is a [`CloneableCart`]) + /// + /// This is a bit more efficient than cloning the [`Yoke`] and then calling [`Yoke::map_project`] + /// because then it will not clone fields that are going to be discarded. + pub fn map_project_cloned<'this, P, F>(&'this self, f: F) -> Yoke + where + P: for<'a> Yokeable<'a>, + C: CloneableCart, + F: for<'a> FnOnce( + &'this >::Output, + PhantomData<&'a ()>, + ) ->

>::Output, + { + let p = f(self.get(), PhantomData); + Yoke { + yokeable: KindaSortaDangling::new(unsafe { P::make(p) }), + cart: self.cart.clone(), + } + } + + /// This is similar to [`Yoke::map_project`], however it can also bubble up an error + /// from the callback. + /// + /// ``` + /// # use std::rc::Rc; + /// # use yoke::Yoke; + /// # use std::str::{self, Utf8Error}; + /// # + /// fn slice( + /// y: Yoke<&'static [u8], Rc<[u8]>>, + /// ) -> Result>, Utf8Error> { + /// y.try_map_project(move |bytes, _| str::from_utf8(bytes)) + /// } + /// ``` + /// + /// This can also be used to create a yoke for a subfield + /// + /// ``` + /// # use std::borrow::Cow; + /// # use yoke::{Yoke, Yokeable}; + /// # use std::mem; + /// # use std::rc::Rc; + /// # use std::str::{self, Utf8Error}; + /// # + /// // also safely implements Yokeable<'a> + /// struct Bar<'a> { + /// bytes_1: &'a [u8], + /// string_2: &'a str, + /// } + /// + /// fn map_project_string_1( + /// bar: Yoke, Rc<[u8]>>, + /// ) -> Result>, Utf8Error> { + /// bar.try_map_project(|bar, _| str::from_utf8(bar.bytes_1)) + /// } + /// + /// # + /// # unsafe impl<'a> Yokeable<'a> for Bar<'static> { + /// # type Output = Bar<'a>; + /// # fn transform(&'a self) -> &'a Bar<'a> { + /// # self + /// # } + /// # + /// # fn transform_owned(self) -> Bar<'a> { + /// # // covariant lifetime cast, can be done safely + /// # self + /// # } + /// # + /// # unsafe fn make(from: Bar<'a>) -> Self { + /// # let ret = mem::transmute_copy(&from); + /// # mem::forget(from); + /// # ret + /// # } + /// # + /// # fn transform_mut(&'a mut self, f: F) + /// # where + /// # F: 'static + FnOnce(&'a mut Self::Output), + /// # { + /// # unsafe { f(mem::transmute(self)) } + /// # } + /// # } + /// ``` + pub fn try_map_project(self, f: F) -> Result, E> + where + P: for<'a> Yokeable<'a>, + F: for<'a> FnOnce( + >::Output, + PhantomData<&'a ()>, + ) -> Result<

>::Output, E>, + { + let p = f(self.yokeable.into_inner().transform_owned(), PhantomData)?; + Ok(Yoke { + yokeable: KindaSortaDangling::new(unsafe { P::make(p) }), + cart: self.cart, + }) + } + + /// This is similar to [`Yoke::try_map_project`], however it does not move + /// [`Self`] and instead clones the cart (only if the cart is a [`CloneableCart`]) + /// + /// This is a bit more efficient than cloning the [`Yoke`] and then calling [`Yoke::map_project`] + /// because then it will not clone fields that are going to be discarded. + pub fn try_map_project_cloned<'this, P, F, E>(&'this self, f: F) -> Result, E> + where + P: for<'a> Yokeable<'a>, + C: CloneableCart, + F: for<'a> FnOnce( + &'this >::Output, + PhantomData<&'a ()>, + ) -> Result<

>::Output, E>, + { + let p = f(self.get(), PhantomData)?; + Ok(Yoke { + yokeable: KindaSortaDangling::new(unsafe { P::make(p) }), + cart: self.cart.clone(), + }) + } + /// This is similar to [`Yoke::map_project`], but it works around older versions + /// of Rust not being able to use `FnOnce` by using an explicit capture input. + /// See [#1061](https://github.com/unicode-org/icu4x/issues/1061). + /// + /// See the docs of [`Yoke::map_project`] for how this works. + pub fn map_project_with_explicit_capture( + self, + capture: T, + f: for<'a> fn( + >::Output, + capture: T, + PhantomData<&'a ()>, + ) ->

>::Output, + ) -> Yoke + where + P: for<'a> Yokeable<'a>, + { + let p = f( + self.yokeable.into_inner().transform_owned(), + capture, + PhantomData, + ); + Yoke { + yokeable: KindaSortaDangling::new(unsafe { P::make(p) }), + cart: self.cart, + } + } + + /// This is similar to [`Yoke::map_project_cloned`], but it works around older versions + /// of Rust not being able to use `FnOnce` by using an explicit capture input. + /// See [#1061](https://github.com/unicode-org/icu4x/issues/1061). + /// + /// See the docs of [`Yoke::map_project_cloned`] for how this works. + pub fn map_project_cloned_with_explicit_capture<'this, P, T>( + &'this self, + capture: T, + f: for<'a> fn( + &'this >::Output, + capture: T, + PhantomData<&'a ()>, + ) ->

>::Output, + ) -> Yoke + where + P: for<'a> Yokeable<'a>, + C: CloneableCart, + { + let p = f(self.get(), capture, PhantomData); + Yoke { + yokeable: KindaSortaDangling::new(unsafe { P::make(p) }), + cart: self.cart.clone(), + } + } + + /// This is similar to [`Yoke::try_map_project`], but it works around older versions + /// of Rust not being able to use `FnOnce` by using an explicit capture input. + /// See [#1061](https://github.com/unicode-org/icu4x/issues/1061). + /// + /// See the docs of [`Yoke::try_map_project`] for how this works. + #[allow(clippy::type_complexity)] + pub fn try_map_project_with_explicit_capture( + self, + capture: T, + f: for<'a> fn( + >::Output, + capture: T, + PhantomData<&'a ()>, + ) -> Result<

>::Output, E>, + ) -> Result, E> + where + P: for<'a> Yokeable<'a>, + { + let p = f( + self.yokeable.into_inner().transform_owned(), + capture, + PhantomData, + )?; + Ok(Yoke { + yokeable: KindaSortaDangling::new(unsafe { P::make(p) }), + cart: self.cart, + }) + } + + /// This is similar to [`Yoke::try_map_project_cloned`], but it works around older versions + /// of Rust not being able to use `FnOnce` by using an explicit capture input. + /// See [#1061](https://github.com/unicode-org/icu4x/issues/1061). + /// + /// See the docs of [`Yoke::try_map_project_cloned`] for how this works. + #[allow(clippy::type_complexity)] + pub fn try_map_project_cloned_with_explicit_capture<'this, P, T, E>( + &'this self, + capture: T, + f: for<'a> fn( + &'this >::Output, + capture: T, + PhantomData<&'a ()>, + ) -> Result<

>::Output, E>, + ) -> Result, E> + where + P: for<'a> Yokeable<'a>, + C: CloneableCart, + { + let p = f(self.get(), capture, PhantomData)?; + Ok(Yoke { + yokeable: KindaSortaDangling::new(unsafe { P::make(p) }), + cart: self.cart.clone(), + }) + } +} + +#[cfg(feature = "alloc")] +impl Yokeable<'a>, C: 'static + Sized> Yoke> { + /// Allows type-erasing the cart in a `Yoke>`. + /// + /// The yoke only carries around a cart type `C` for its destructor, + /// since it needs to be able to guarantee that its internal references + /// are valid for the lifetime of the Yoke. As such, the actual type of the + /// Cart is not very useful unless you wish to extract data out of it + /// via [`Yoke::backing_cart()`]. Erasing the cart allows for one to mix + /// [`Yoke`]s obtained from different sources. + /// + /// In case the cart type `C` is not already an `Rc`, you can use + /// [`Yoke::wrap_cart_in_rc()`] to wrap it. + /// + /// ✨ *Enabled with the `alloc` Cargo feature.* + /// + /// # Example + /// + /// ```rust + /// use std::rc::Rc; + /// use yoke::erased::ErasedRcCart; + /// use yoke::Yoke; + /// + /// let buffer1: Rc = Rc::new(" foo bar baz ".into()); + /// let buffer2: Box = Box::new(" baz quux ".into()); + /// + /// let yoke1 = + /// Yoke::<&'static str, _>::attach_to_cart(buffer1, |rc| rc.trim()); + /// let yoke2 = Yoke::<&'static str, _>::attach_to_cart(buffer2, |b| b.trim()); + /// + /// let erased1: Yoke<_, ErasedRcCart> = yoke1.erase_rc_cart(); + /// // Wrap the Box in an Rc to make it compatible + /// let erased2: Yoke<_, ErasedRcCart> = + /// yoke2.wrap_cart_in_rc().erase_rc_cart(); + /// + /// // Now erased1 and erased2 have the same type! + /// ``` + pub fn erase_rc_cart(self) -> Yoke { + unsafe { + // safe because the cart is preserved, just + // type-erased + self.replace_cart(|c| c as ErasedRcCart) + } + } +} + +#[cfg(feature = "alloc")] +impl Yokeable<'a>, C: 'static + Sized + Send + Sync> Yoke> { + /// Allows type-erasing the cart in a `Yoke>`. + /// + /// The yoke only carries around a cart type `C` for its destructor, + /// since it needs to be able to guarantee that its internal references + /// are valid for the lifetime of the Yoke. As such, the actual type of the + /// Cart is not very useful unless you wish to extract data out of it + /// via [`Yoke::backing_cart()`]. Erasing the cart allows for one to mix + /// [`Yoke`]s obtained from different sources. + /// + /// In case the cart type `C` is not already an `Arc`, you can use + /// [`Yoke::wrap_cart_in_arc()`] to wrap it. + /// + /// ✨ *Enabled with the `alloc` Cargo feature.* + /// + /// # Example + /// + /// ```rust + /// use std::sync::Arc; + /// use yoke::erased::ErasedArcCart; + /// use yoke::Yoke; + /// + /// let buffer1: Arc = Arc::new(" foo bar baz ".into()); + /// let buffer2: Box = Box::new(" baz quux ".into()); + /// + /// let yoke1 = + /// Yoke::<&'static str, _>::attach_to_cart(buffer1, |arc| arc.trim()); + /// let yoke2 = Yoke::<&'static str, _>::attach_to_cart(buffer2, |b| b.trim()); + /// + /// let erased1: Yoke<_, ErasedArcCart> = yoke1.erase_arc_cart(); + /// // Wrap the Box in an Rc to make it compatible + /// let erased2: Yoke<_, ErasedArcCart> = + /// yoke2.wrap_cart_in_arc().erase_arc_cart(); + /// + /// // Now erased1 and erased2 have the same type! + /// ``` + pub fn erase_arc_cart(self) -> Yoke { + unsafe { + // safe because the cart is preserved, just + // type-erased + self.replace_cart(|c| c as ErasedArcCart) + } + } +} + +#[cfg(feature = "alloc")] +impl Yokeable<'a>, C: 'static + Sized> Yoke> { + /// Allows type-erasing the cart in a `Yoke>`. + /// + /// The yoke only carries around a cart type `C` for its destructor, + /// since it needs to be able to guarantee that its internal references + /// are valid for the lifetime of the Yoke. As such, the actual type of the + /// Cart is not very useful unless you wish to extract data out of it + /// via [`Yoke::backing_cart()`]. Erasing the cart allows for one to mix + /// [`Yoke`]s obtained from different sources. + /// + /// In case the cart type `C` is not already `Box`, you can use + /// [`Yoke::wrap_cart_in_box()`] to wrap it. + /// + /// ✨ *Enabled with the `alloc` Cargo feature.* + /// + /// # Example + /// + /// ```rust + /// use std::rc::Rc; + /// use yoke::erased::ErasedBoxCart; + /// use yoke::Yoke; + /// + /// let buffer1: Rc = Rc::new(" foo bar baz ".into()); + /// let buffer2: Box = Box::new(" baz quux ".into()); + /// + /// let yoke1 = + /// Yoke::<&'static str, _>::attach_to_cart(buffer1, |rc| rc.trim()); + /// let yoke2 = Yoke::<&'static str, _>::attach_to_cart(buffer2, |b| b.trim()); + /// + /// // Wrap the Rc in an Box to make it compatible + /// let erased1: Yoke<_, ErasedBoxCart> = + /// yoke1.wrap_cart_in_box().erase_box_cart(); + /// let erased2: Yoke<_, ErasedBoxCart> = yoke2.erase_box_cart(); + /// + /// // Now erased1 and erased2 have the same type! + /// ``` + pub fn erase_box_cart(self) -> Yoke { + unsafe { + // safe because the cart is preserved, just + // type-erased + self.replace_cart(|c| c as ErasedBoxCart) + } + } +} + +#[cfg(feature = "alloc")] +impl Yokeable<'a>, C> Yoke { + /// Helper function allowing one to wrap the cart type `C` in a `Box`. + /// Can be paired with [`Yoke::erase_box_cart()`] + /// + /// ✨ *Enabled with the `alloc` Cargo feature.* + #[inline] + pub fn wrap_cart_in_box(self) -> Yoke> { + unsafe { + // safe because the cart is preserved, just wrapped + self.replace_cart(Box::new) + } + } + /// Helper function allowing one to wrap the cart type `C` in an `Rc`. + /// Can be paired with [`Yoke::erase_rc_cart()`], or generally used + /// to make the [`Yoke`] cloneable. + /// + /// ✨ *Enabled with the `alloc` Cargo feature.* + #[inline] + pub fn wrap_cart_in_rc(self) -> Yoke> { + unsafe { + // safe because the cart is preserved, just wrapped + self.replace_cart(Rc::new) + } + } + /// Helper function allowing one to wrap the cart type `C` in an `Rc`. + /// Can be paired with [`Yoke::erase_arc_cart()`], or generally used + /// to make the [`Yoke`] cloneable. + /// + /// ✨ *Enabled with the `alloc` Cargo feature.* + #[inline] + pub fn wrap_cart_in_arc(self) -> Yoke> { + unsafe { + // safe because the cart is preserved, just wrapped + self.replace_cart(Arc::new) + } + } +} + +impl Yokeable<'a>, C> Yoke { + /// Helper function allowing one to wrap the cart type `C` in an [`EitherCart`]. + /// + /// This function wraps the cart into the `A` variant. To wrap it into the + /// `B` variant, use [`Self::wrap_cart_in_either_b()`]. + /// + /// For an example, see [`EitherCart`]. + #[inline] + pub fn wrap_cart_in_either_a(self) -> Yoke> { + unsafe { + // safe because the cart is preserved, just wrapped + self.replace_cart(EitherCart::A) + } + } + /// Helper function allowing one to wrap the cart type `C` in an [`EitherCart`]. + /// + /// This function wraps the cart into the `B` variant. To wrap it into the + /// `A` variant, use [`Self::wrap_cart_in_either_a()`]. + /// + /// For an example, see [`EitherCart`]. + #[inline] + pub fn wrap_cart_in_either_b(self) -> Yoke> { + unsafe { + // safe because the cart is preserved, just wrapped + self.replace_cart(EitherCart::B) + } + } +} + +/// # Safety docs for project() +/// +/// (Docs are on a private const to allow the use of compile_fail doctests) +/// +/// This is safe to perform because of the choice of lifetimes on `f`, that is, +/// `for fn(>::Output, &'a ()) ->

>::Output`. +/// +/// What we want this function to do is take a Yokeable (`Y`) that is borrowing from the cart, and +/// produce another Yokeable (`P`) that also borrows from the same cart. There are a couple potential +/// hazards here: +/// +/// - `P` ends up borrowing data from `Y` (or elsewhere) that did _not_ come from the cart, +/// for example `P` could borrow owned data from a `Cow`. This would make the `Yoke

` dependent +/// on data owned only by the `Yoke`. +/// - Borrowed data from `Y` escapes with the wrong lifetime +/// +/// Let's walk through these and see how they're prevented. +/// +/// ```rust, compile_fail +/// # use std::rc::Rc; +/// # use yoke::Yoke; +/// # use std::borrow::Cow; +/// fn borrow_potentially_owned(y: &Yoke, Rc<[u8]>>) -> Yoke<&'static str, Rc<[u8]>> { +/// y.map_project_cloned(|cow, _| &*cow) +/// } +/// ``` +/// +/// In this case, the lifetime of `&*cow` is `&'this str`, however the function needs to be able to return +/// `&'a str` _for all `'a`_, which isn't possible. +/// +/// +/// ```rust, compile_fail +/// # use std::rc::Rc; +/// # use yoke::Yoke; +/// # use std::borrow::Cow; +/// fn borrow_potentially_owned(y: Yoke, Rc<[u8]>>) -> Yoke<&'static str, Rc<[u8]>> { +/// y.map_project(|cow, _| &*cow) +/// } +/// ``` +/// +/// This has the same issue, `&*cow` is borrowing for a local lifetime. +/// +/// Similarly, trying to project an owned field of a struct will produce similar errors: +/// +/// ```rust,compile_fail +/// # use std::borrow::Cow; +/// # use yoke::{Yoke, Yokeable}; +/// # use std::mem; +/// # use std::rc::Rc; +/// # +/// // also safely implements Yokeable<'a> +/// struct Bar<'a> { +/// owned: String, +/// string_2: &'a str, +/// } +/// +/// fn map_project_owned(bar: &Yoke, Rc<[u8]>>) -> Yoke<&'static str, Rc<[u8]>> { +/// // ERROR (but works if you replace owned with string_2) +/// bar.map_project_cloned(|bar, _| &*bar.owned) +/// } +/// +/// # +/// # unsafe impl<'a> Yokeable<'a> for Bar<'static> { +/// # type Output = Bar<'a>; +/// # fn transform(&'a self) -> &'a Bar<'a> { +/// # self +/// # } +/// # +/// # fn transform_owned(self) -> Bar<'a> { +/// # // covariant lifetime cast, can be done safely +/// # self +/// # } +/// # +/// # unsafe fn make(from: Bar<'a>) -> Self { +/// # let ret = mem::transmute_copy(&from); +/// # mem::forget(from); +/// # ret +/// # } +/// # +/// # fn transform_mut(&'a mut self, f: F) +/// # where +/// # F: 'static + FnOnce(&'a mut Self::Output), +/// # { +/// # unsafe { f(mem::transmute(self)) } +/// # } +/// # } +/// ``` +/// +/// Borrowed data from `Y` similarly cannot escape with the wrong lifetime because of the `for<'a>`, since +/// it will never be valid for the borrowed data to escape for all lifetimes of 'a. Internally, `.project()` +/// uses `.get()`, however the signature forces the callers to be able to handle every lifetime. +/// +/// `'a` is the only lifetime that matters here; `Yokeable`s must be `'static` and since +/// `Output` is an associated type it can only have one lifetime, `'a` (there's nowhere for it to get another from). +/// `Yoke`s can get additional lifetimes via the cart, and indeed, `project()` can operate on `Yoke<_, &'b [u8]>`, +/// however this lifetime is inaccessible to the closure, and even if it were accessible the `for<'a>` would force +/// it out of the output. All external lifetimes (from other found outside the yoke/closures +/// are similarly constrained here. +/// +/// Essentially, safety is achieved by using `for<'a> fn(...)` with `'a` used in both `Yokeable`s to ensure that +/// the output yokeable can _only_ have borrowed data flow in to it from the input. All paths of unsoundness require the +/// unification of an existential and universal lifetime, which isn't possible. +const _: () = (); + +/// # Safety docs for attach_to_cart()'s signature +/// +/// The `attach_to_cart()` family of methods get by by using the following bound: +/// +/// ```rust,ignore +/// F: for<'de> FnOnce(&'de ::Target) -> >::Output, +/// C::Target: 'static +/// ``` +/// +/// to enforce that the yoking closure produces a yokeable that is *only* allowed to borrow from the cart. +/// A way to be sure of this is as follows: imagine if `F` *did* borrow data of lifetime `'a` and stuff it in +/// its output. Then that lifetime `'a` would have to live at least as long as `'de` *for all `'de`*. +/// The only lifetime that satisfies that is `'static` (since at least one of the potential `'de`s is `'static`), +/// and we're fine with that. +/// +/// ## Implied bounds and variance +/// +/// The `C::Target: 'static` bound is tricky, however. Let's imagine a situation where we *didn't* have that bound. +/// +/// One thing to remember is that we are okay with the cart itself borrowing from places, +/// e.g. `&[u8]` is a valid cart, as is `Box<&[u8]>`. `C` is not `'static`. +/// +/// (I'm going to use `CT` in prose to refer to `C::Target` here, since almost everything here has to do +/// with C::Target and not C itself.) +/// +/// Unfortunately, there's a sneaky additional bound inside `F`. The signature of `F` is *actually* +/// +/// ```rust,ignore +/// F: for<'de> where FnOnce(&'de C::Target) -> >::Output +/// ``` +/// +/// using made-up "where clause inside HRTB" syntax to represent a type that can be represented inside the compiler +/// and type system but not in Rust code. The `CT: 'de` bond comes from the `&'de C::Target`: any time you +/// write `&'a T`, an implied bound of `T: 'a` materializes and is stored alongside it, since references cannot refer +/// to data that itself refers to data of shorter lifetimes. If a reference is valid, its referent must be valid for +/// the duration of the reference's lifetime, so every reference *inside* its referent must also be valid, giving us `T: 'a`. +/// This kind of constraint is often called a "well formedness" constraint: `&'a T` is not "well formed" without that +/// bound, and rustc is being helpful by giving it to us for free. +/// +/// Unfortunately, this messes with our universal quantification. The `for<'de>` is no longer "For all lifetimes `'de`", +/// it is "for all lifetimes `'de` *where `CT: 'de`*". And if `CT` borrows from somewhere (with lifetime `'ct`), then we get a +/// `'ct: 'de` bound, and `'de` candidates that live longer than `'ct` won't actually be considered. +/// The neat little logic at the beginning stops working. +/// +/// `attach_to_cart()` will instead enforce that the produced yokeable *either* borrows from the cart (fine), or from +/// data that has a lifetime that is at least `'ct`. Which means that `attach_to_cart()` will allow us to borrow locals +/// provided they live at least as long as `'ct`. +/// +/// Is this a problem? +/// +/// This is totally fine if CT's lifetime is covariant: if C is something like `Box<&'ct [u8]>`, even if our +/// yoked object borrows from locals outliving `'ct`, our Yoke can't outlive that +/// lifetime `'ct` anyway (since it's a part of the cart type), so we're fine. +/// +/// However it's completely broken for contravariant carts (e.g. `Box`). In that case +/// we still get `'ct: 'de`, and we still end up being able to +/// borrow from locals that outlive `'ct`. However, our Yoke _can_ outlive +/// that lifetime, because Yoke shares its variance over `'ct` +/// with the cart type, and the cart type is contravariant over `'ct`. +/// So the Yoke can be upcast to having a longer lifetime than `'ct`, and *that* Yoke +/// can outlive `'ct`. +/// +/// We fix this by forcing `C::Target: 'static` in `attach_to_cart()`, which would make it work +/// for fewer types, but would also allow Yoke to continue to be covariant over cart lifetimes if necessary. +/// +/// An alternate fix would be to not allowing yoke to ever be upcast over lifetimes contained in the cart +/// by forcing them to be invariant. This is a bit more restrictive and affects *all* `Yoke` users, not just +/// those using `attach_to_cart()`. +/// +/// See https://github.com/unicode-org/icu4x/issues/2926 +/// See also https://github.com/rust-lang/rust/issues/106431 for potentially fixing this upstream by +/// changing how the bound works. +/// +/// # Tests +/// +/// Here's a broken `attach_to_cart()` that attempts to borrow from a local: +/// +/// ```rust,compile_fail +/// use yoke::{Yoke, Yokeable}; +/// +/// let cart = vec![1, 2, 3, 4].into_boxed_slice(); +/// let local = vec![4, 5, 6, 7]; +/// let yoke: Yoke<&[u8], Box<[u8]>> = Yoke::attach_to_cart(cart, |_| &*local); +/// ``` +/// +/// Fails as expected. +/// +/// And here's a working one with a local borrowed cart that does not do any sneaky borrows whilst attaching. +/// +/// ```rust +/// use yoke::{Yoke, Yokeable}; +/// +/// let cart = vec![1, 2, 3, 4].into_boxed_slice(); +/// let local = vec![4, 5, 6, 7]; +/// let yoke: Yoke<&[u8], &[u8]> = Yoke::attach_to_cart(&cart, |c| &*c); +/// ``` +/// +/// Here's an `attach_to_cart()` that attempts to borrow from a longer-lived local due to +/// the cart being covariant. It fails, but would not if the alternate fix of forcing Yoke to be invariant +/// were implemented. It is technically a safe operation: +/// +/// ```rust,compile_fail +/// use yoke::{Yoke, Yokeable}; +/// // longer lived +/// let local = vec![4, 5, 6, 7]; +/// +/// let backing = vec![1, 2, 3, 4]; +/// let cart = Box::new(&*backing); +/// +/// let yoke: Yoke<&[u8], Box<&[u8]>> = Yoke::attach_to_cart(cart, |_| &*local); +/// println!("{:?}", yoke.get()); +/// ``` +/// +/// Finally, here's an `attach_to_cart()` that attempts to borrow from a longer lived local +/// in the case of a contravariant lifetime. It does not compile, but in and of itself is not dangerous: +/// +/// ```rust,compile_fail +/// use yoke::Yoke; +/// +/// type Contra<'a> = fn(&'a ()); +/// +/// let local = String::from("Hello World!"); +/// let yoke: Yoke<&'static str, Box>> = Yoke::attach_to_cart(Box::new((|_| {}) as _), |_| &local[..]); +/// println!("{:?}", yoke.get()); +/// ``` +/// +/// It is dangerous if allowed to transform (testcase from #2926) +/// +/// ```rust,compile_fail +/// use yoke::Yoke; +/// +/// type Contra<'a> = fn(&'a ()); +/// +/// +/// let local = String::from("Hello World!"); +/// let yoke: Yoke<&'static str, Box>> = Yoke::attach_to_cart(Box::new((|_| {}) as _), |_| &local[..]); +/// println!("{:?}", yoke.get()); +/// let yoke_longer: Yoke<&'static str, Box>> = yoke; +/// let leaked: &'static Yoke<&'static str, Box>> = Box::leak(Box::new(yoke_longer)); +/// let reference: &'static str = leaked.get(); +/// +/// println!("pre-drop: {reference}"); +/// drop(local); +/// println!("post-drop: {reference}"); +/// ``` +const _: () = (); diff --git a/third_party/rust/yoke/src/yokeable.rs b/third_party/rust/yoke/src/yokeable.rs new file mode 100644 index 0000000000..73e81aa7b5 --- /dev/null +++ b/third_party/rust/yoke/src/yokeable.rs @@ -0,0 +1,325 @@ +// This file is part of ICU4X. For terms of use, please see the file +// called LICENSE at the top level of the ICU4X source tree +// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ). + +#[cfg(feature = "alloc")] +use alloc::borrow::{Cow, ToOwned}; +use core::mem; + +/// The `Yokeable<'a>` trait is implemented on the `'static` version of any zero-copy type; for +/// example, `Cow<'static, T>` implements `Yokeable<'a>` (for all `'a`). One can use +/// `Yokeable::Output` on this trait to obtain the "lifetime'd" value of the `Cow<'static, T>`, +/// e.g. ` as Yokeable<'a>'>::Output` is `Cow<'a, T>`. +/// +/// A [`Yokeable`] type is essentially one with a covariant lifetime parameter, +/// matched to the parameter in the trait definition. The trait allows one to cast +/// the covariant lifetime to and from `'static`. +/// +/// **Most of the time, if you need to implement [`Yokeable`], you should be able to use the safe +/// [`#[derive(Yokeable)]`](yoke_derive::Yokeable) custom derive.** +/// +/// While Rust does not yet have GAT syntax, for the purpose of this documentation +/// we shall refer to "`Self` with a lifetime `'a`" with the syntax `Self<'a>`. +/// Self<'static> is a stand-in for the HKT Self<'_>: lifetime -> type. +/// +/// With this terminology, [`Yokeable`] exposes ways to cast between `Self<'static>` and `Self<'a>` generically. +/// This is useful for turning covariant lifetimes to _dynamic_ lifetimes, where `'static` is +/// used as a way to "erase" the lifetime. +/// +/// # Safety +/// +/// This trait is safe to implement on types with a _covariant_ lifetime parameter, i.e. one where +/// [`Self::transform()`]'s body can simply be `{ self }`. This will occur when the lifetime +/// parameter is used within references, but not in the arguments of function pointers or in mutable +/// positions (either in `&mut` or via interior mutability) +/// +/// This trait must be implemented on the `'static` version of such a type, e.g. one should +/// implement `Yokeable<'a>` (for all `'a`) on `Cow<'static, T>`. +/// +/// There are further constraints on implementation safety on individual methods. +/// +/// # Trait bounds +/// +/// [Compiler bug #85636](https://github.com/rust-lang/rust/issues/85636) makes it tricky to add +/// trait bounds on `Yokeable::Output`. For more information and for workarounds, see +/// [`crate::trait_hack`]. +/// +/// # Implementation example +/// +/// Implementing this trait manually is unsafe. Where possible, you should use the safe +/// [`#[derive(Yokeable)]`](yoke_derive::Yokeable) custom derive instead. We include an example +/// in case you have your own zero-copy abstractions you wish to make yokeable. +/// +/// ```rust +/// # use yoke::Yokeable; +/// # use std::borrow::Cow; +/// # use std::{mem, ptr}; +/// struct Bar<'a> { +/// numbers: Cow<'a, [u8]>, +/// string: Cow<'a, str>, +/// owned: Vec, +/// } +/// +/// unsafe impl<'a> Yokeable<'a> for Bar<'static> { +/// type Output = Bar<'a>; +/// fn transform(&'a self) -> &'a Bar<'a> { +/// // covariant lifetime cast, can be done safely +/// self +/// } +/// +/// fn transform_owned(self) -> Bar<'a> { +/// // covariant lifetime cast, can be done safely +/// self +/// } +/// +/// unsafe fn make(from: Bar<'a>) -> Self { +/// // We're just doing mem::transmute() here, however Rust is +/// // not smart enough to realize that Bar<'a> and Bar<'static> are of +/// // the same size, so instead we use transmute_copy +/// +/// // This assert will be optimized out, but is included for additional +/// // peace of mind as we are using transmute_copy +/// debug_assert!(mem::size_of::>() == mem::size_of::()); +/// let ptr: *const Self = (&from as *const Self::Output).cast(); +/// mem::forget(from); +/// ptr::read(ptr) +/// } +/// +/// fn transform_mut(&'a mut self, f: F) +/// where +/// F: 'static + FnOnce(&'a mut Self::Output), +/// { +/// unsafe { f(mem::transmute::<&mut Self, &mut Self::Output>(self)) } +/// } +/// } +/// ``` +pub unsafe trait Yokeable<'a>: 'static { + /// This type MUST be `Self` with the `'static` replaced with `'a`, i.e. `Self<'a>` + type Output: 'a; + + /// This method must cast `self` between `&'a Self<'static>` and `&'a Self<'a>`. + /// + /// # Implementation safety + /// + /// If the invariants of [`Yokeable`] are being satisfied, the body of this method + /// should simply be `{ self }`, though it's acceptable to include additional assertions + /// if desired. + fn transform(&'a self) -> &'a Self::Output; + + /// This method must cast `self` between `Self<'static>` and `Self<'a>`. + /// + /// # Implementation safety + /// + /// If the invariants of [`Yokeable`] are being satisfied, the body of this method + /// should simply be `{ self }`, though it's acceptable to include additional assertions + /// if desired. + fn transform_owned(self) -> Self::Output; + + /// This method can be used to cast away `Self<'a>`'s lifetime. + /// + /// # Safety + /// + /// The returned value must be destroyed before the data `from` was borrowing from is. + /// + /// # Implementation safety + /// + /// A safe implementation of this method must be equivalent to a transmute between + /// `Self<'a>` and `Self<'static>` + unsafe fn make(from: Self::Output) -> Self; + + /// This method must cast `self` between `&'a mut Self<'static>` and `&'a mut Self<'a>`, + /// and pass it to `f`. + /// + /// # Implementation safety + /// + /// A safe implementation of this method must be equivalent to a pointer cast/transmute between + /// `&mut Self<'a>` and `&mut Self<'static>` being passed to `f` + /// + /// # Why is this safe? + /// + /// Typically covariant lifetimes become invariant when hidden behind an `&mut`, + /// which is why the implementation of this method cannot just be `f(self)`. + /// The reason behind this is that while _reading_ a covariant lifetime that has been cast to a shorter + /// one is always safe (this is roughly the definition of a covariant lifetime), writing + /// may not necessarily be safe since you could write a smaller reference to it. For example, + /// the following code is unsound because it manages to stuff a `'a` lifetime into a `Cow<'static>` + /// + /// ```rust,compile_fail + /// # use std::borrow::Cow; + /// # use yoke::Yokeable; + /// struct Foo { + /// str: String, + /// cow: Cow<'static, str>, + /// } + /// + /// fn unsound<'a>(foo: &'a mut Foo) { + /// let a: &str = &foo.str; + /// foo.cow.transform_mut(|cow| *cow = Cow::Borrowed(a)); + /// } + /// ``` + /// + /// However, this code will not compile because [`Yokeable::transform_mut()`] requires `F: 'static`. + /// This enforces that while `F` may mutate `Self<'a>`, it can only mutate it in a way that does + /// not insert additional references. For example, `F` may call `to_owned()` on a `Cow` and mutate it, + /// but it cannot insert a new _borrowed_ reference because it has nowhere to borrow _from_ -- + /// `f` does not contain any borrowed references, and while we give it `Self<'a>` (which contains borrowed + /// data), that borrowed data is known to be valid + /// + /// Note that the `for<'b>` is also necessary, otherwise the following code would compile: + /// + /// ```rust,compile_fail + /// # use std::borrow::Cow; + /// # use yoke::Yokeable; + /// # use std::mem; + /// # + /// // also safely implements Yokeable<'a> + /// struct Bar<'a> { + /// num: u8, + /// cow: Cow<'a, u8>, + /// } + /// + /// fn unsound<'a>(bar: &'a mut Bar<'static>) { + /// bar.transform_mut(move |bar| bar.cow = Cow::Borrowed(&bar.num)); + /// } + /// # + /// # unsafe impl<'a> Yokeable<'a> for Bar<'static> { + /// # type Output = Bar<'a>; + /// # fn transform(&'a self) -> &'a Bar<'a> { + /// # self + /// # } + /// # + /// # fn transform_owned(self) -> Bar<'a> { + /// # // covariant lifetime cast, can be done safely + /// # self + /// # } + /// # + /// # unsafe fn make(from: Bar<'a>) -> Self { + /// # let ret = mem::transmute_copy(&from); + /// # mem::forget(from); + /// # ret + /// # } + /// # + /// # fn transform_mut(&'a mut self, f: F) + /// # where + /// # F: 'static + FnOnce(&'a mut Self::Output), + /// # { + /// # unsafe { f(mem::transmute(self)) } + /// # } + /// # } + /// ``` + /// + /// which is unsound because `bar` could be moved later, and we do not want to be able to + /// self-insert references to it. + /// + /// The `for<'b>` enforces this by stopping the author of the closure from matching up the input + /// `&'b Self::Output` lifetime with `'a` and borrowing directly from it. + /// + /// Thus the only types of mutations allowed are ones that move around already-borrowed data, or + /// introduce new owned data: + /// + /// ```rust + /// # use std::borrow::Cow; + /// # use yoke::Yokeable; + /// struct Foo { + /// str: String, + /// cow: Cow<'static, str>, + /// } + /// + /// fn sound<'a>(foo: &'a mut Foo) { + /// foo.cow.transform_mut(move |cow| cow.to_mut().push('a')); + /// } + /// ``` + fn transform_mut(&'a mut self, f: F) + where + // be VERY CAREFUL changing this signature, it is very nuanced (see above) + F: 'static + for<'b> FnOnce(&'b mut Self::Output); +} + +#[cfg(feature = "alloc")] +unsafe impl<'a, T: 'static + ToOwned + ?Sized> Yokeable<'a> for Cow<'static, T> +where + ::Owned: Sized, +{ + type Output = Cow<'a, T>; + #[inline] + fn transform(&'a self) -> &'a Cow<'a, T> { + // Doesn't need unsafe: `'a` is covariant so this lifetime cast is always safe + self + } + #[inline] + fn transform_owned(self) -> Cow<'a, T> { + // Doesn't need unsafe: `'a` is covariant so this lifetime cast is always safe + self + } + #[inline] + unsafe fn make(from: Cow<'a, T>) -> Self { + // i hate this + // unfortunately Rust doesn't think `mem::transmute` is possible since it's not sure the sizes + // are the same + debug_assert!(mem::size_of::>() == mem::size_of::()); + let ptr: *const Self = (&from as *const Self::Output).cast(); + mem::forget(from); + core::ptr::read(ptr) + } + #[inline] + fn transform_mut(&'a mut self, f: F) + where + F: 'static + for<'b> FnOnce(&'b mut Self::Output), + { + // Cast away the lifetime of Self + unsafe { f(mem::transmute::<&'a mut Self, &'a mut Self::Output>(self)) } + } +} + +unsafe impl<'a, T: 'static + ?Sized> Yokeable<'a> for &'static T { + type Output = &'a T; + #[inline] + fn transform(&'a self) -> &'a &'a T { + // Doesn't need unsafe: `'a` is covariant so this lifetime cast is always safe + self + } + #[inline] + fn transform_owned(self) -> &'a T { + // Doesn't need unsafe: `'a` is covariant so this lifetime cast is always safe + self + } + #[inline] + unsafe fn make(from: &'a T) -> Self { + mem::transmute(from) + } + #[inline] + fn transform_mut(&'a mut self, f: F) + where + F: 'static + for<'b> FnOnce(&'b mut Self::Output), + { + // Cast away the lifetime of Self + unsafe { f(mem::transmute::<&'a mut Self, &'a mut Self::Output>(self)) } + } +} + +#[cfg(feature = "alloc")] +unsafe impl<'a, T: 'static> Yokeable<'a> for alloc::vec::Vec { + type Output = alloc::vec::Vec; + #[inline] + fn transform(&'a self) -> &'a alloc::vec::Vec { + // Doesn't need unsafe: `'a` is covariant so this lifetime cast is always safe + self + } + #[inline] + fn transform_owned(self) -> alloc::vec::Vec { + // Doesn't need unsafe: `'a` is covariant so this lifetime cast is always safe + self + } + #[inline] + unsafe fn make(from: alloc::vec::Vec) -> Self { + from + } + #[inline] + fn transform_mut(&'a mut self, f: F) + where + F: 'static + for<'b> FnOnce(&'b mut Self::Output), + { + // Doesn't need unsafe: `'a` is covariant so this lifetime cast is always safe + f(self) + } +} diff --git a/third_party/rust/yoke/src/zero_from.rs b/third_party/rust/yoke/src/zero_from.rs new file mode 100644 index 0000000000..d876d9c06a --- /dev/null +++ b/third_party/rust/yoke/src/zero_from.rs @@ -0,0 +1,57 @@ +// This file is part of ICU4X. For terms of use, please see the file +// called LICENSE at the top level of the ICU4X source tree +// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ). + +use crate::trait_hack::YokeTraitHack; +use crate::Yoke; +use crate::Yokeable; + +use core::ops::Deref; +use stable_deref_trait::StableDeref; + +use crate::ZeroFrom; + +impl<'zf, C: ?Sized, T> ZeroFrom<'zf, C> for YokeTraitHack +where + T: ZeroFrom<'zf, C>, +{ + #[inline] + fn zero_from(cart: &'zf C) -> Self { + YokeTraitHack(T::zero_from(cart)) + } +} + +impl Yoke +where + Y: for<'a> Yokeable<'a>, + for<'a> YokeTraitHack<>::Output>: ZeroFrom<'a, ::Target>, + C: StableDeref + Deref, + ::Target: 'static, +{ + /// Construct a [`Yoke`]`` from a cart implementing `StableDeref` by zero-copy cloning + /// the cart to `Y` and then yokeing that object to the cart. + /// + /// The type `Y` must implement [`ZeroFrom`]``. This trait is auto-implemented + /// on many common types and can be custom implemented or derived in order to make it easier + /// to construct a `Yoke`. + /// + /// # Example + /// + /// Attach to a cart: + /// + /// ``` + /// use std::borrow::Cow; + /// use yoke::Yoke; + /// + /// let yoke = Yoke::, String>::attach_to_zero_copy_cart( + /// "demo".to_owned(), + /// ); + /// + /// assert_eq!("demo", yoke.get()); + /// ``` + pub fn attach_to_zero_copy_cart(cart: C) -> Self { + Yoke::::attach_to_cart(cart, |c| { + YokeTraitHack::<::Output>::zero_from(c).0 + }) + } +} diff --git a/third_party/rust/yoke/tests/bincode.rs b/third_party/rust/yoke/tests/bincode.rs new file mode 100644 index 0000000000..7211e46ffa --- /dev/null +++ b/third_party/rust/yoke/tests/bincode.rs @@ -0,0 +1,83 @@ +// This file is part of ICU4X. For terms of use, please see the file +// called LICENSE at the top level of the ICU4X source tree +// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ). + +// This test is a duplicate of one of the doctests, but is written separately +// since `cargo miri test` doesn't work on doctests yet + +use std::borrow::Cow; +use std::mem; +use std::rc::Rc; +use yoke::{Yoke, Yokeable}; + +fn load_from_cache(_filename: &str) -> Rc<[u8]> { + // dummy implementation + Rc::new([0x5, 0, 0, 0, 0, 0, 0, 0, 0x68, 0x65, 0x6c, 0x6c, 0x6f]) +} + +fn load_object(filename: &str) -> Yoke, Rc<[u8]>> { + let rc: Rc<[u8]> = load_from_cache(filename); + Yoke::, Rc<[u8]>>::attach_to_cart(rc, |data: &[u8]| { + // A real implementation would properly deserialize `Bar` as a whole + Bar { + numbers: Cow::Borrowed(bincode::deserialize(data).unwrap()), + string: Cow::Borrowed(bincode::deserialize(data).unwrap()), + owned: Vec::new(), + } + }) +} + +// also implements Yokeable +struct Bar<'a> { + numbers: Cow<'a, [u8]>, + string: Cow<'a, str>, + owned: Vec, +} + +unsafe impl<'a> Yokeable<'a> for Bar<'static> { + type Output = Bar<'a>; + #[inline] + fn transform(&'a self) -> &'a Bar<'a> { + self + } + #[inline] + fn transform_owned(self) -> Bar<'a> { + self + } + #[inline] + unsafe fn make(from: Bar<'a>) -> Self { + let ret = mem::transmute_copy(&from); + mem::forget(from); + ret + } + #[inline] + fn transform_mut(&'a mut self, f: F) + where + F: 'static + FnOnce(&'a mut Self::Output), + { + unsafe { f(mem::transmute(self)) } + } +} + +#[test] +fn test_load() { + // `load_object()` deserializes an object from a file + let mut bar = load_object("filename.bincode"); + assert_eq!(bar.get().string, "hello"); + assert!(matches!(bar.get().string, Cow::Borrowed(_))); + assert_eq!(&*bar.get().numbers, &[0x68, 0x65, 0x6c, 0x6c, 0x6f]); + assert!(matches!(bar.get().numbers, Cow::Borrowed(_))); + assert_eq!(&*bar.get().owned, &[]); + + bar.with_mut(|bar| { + bar.string.to_mut().push_str(" world"); + bar.owned.extend_from_slice(&[1, 4, 1, 5, 9]); + }); + + assert_eq!(bar.get().string, "hello world"); + assert!(matches!(bar.get().string, Cow::Owned(_))); + assert_eq!(&*bar.get().owned, &[1, 4, 1, 5, 9]); + // Unchanged and still Cow::Borrowed + assert_eq!(&*bar.get().numbers, &[0x68, 0x65, 0x6c, 0x6c, 0x6f]); + assert!(matches!(bar.get().numbers, Cow::Borrowed(_))); +} diff --git a/third_party/rust/yoke/tests/miri.rs b/third_party/rust/yoke/tests/miri.rs new file mode 100644 index 0000000000..0b92af2cc2 --- /dev/null +++ b/third_party/rust/yoke/tests/miri.rs @@ -0,0 +1,15 @@ +// This file is part of ICU4X. For terms of use, please see the file +// called LICENSE at the top level of the ICU4X source tree +// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ). + +use yoke::Yoke; + +// Test for strong protection, should pass under miri with -Zmiri-retag-fields +// See https://github.com/unicode-org/icu4x/issues/3696 + +fn example(_: Yoke<&'static [u8], Vec>) {} + +#[test] +fn run_test() { + example(Yoke::attach_to_cart(vec![0, 1, 2], |data| data)); +} -- cgit v1.2.3