yoke-0.8.0/.cargo_vcs_info.json0000644000000001500000000000100120040ustar { "git": { "sha1": "f4290a877dfcb0f87cad6de4abdd65f0cbb33c9c" }, "path_in_vcs": "utils/yoke" }yoke-0.8.0/Cargo.lock0000644000000066460000000000100077770ustar # This file is automatically @generated by Cargo. # It is not intended for manual editing. version = 3 [[package]] name = "bincode" version = "1.3.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "b1f45e9417d87227c7a56d22e471c6206462cba514c7590c09aff4cf6d1ddcad" dependencies = [ "serde", ] [[package]] name = "cobs" version = "0.2.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "67ba02a97a2bd10f4b59b25c7973101c79642302776489e030cd13cdab09ed15" [[package]] name = "postcard" version = "1.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "170a2601f67cc9dba8edd8c4870b15f71a6a2dc196daec8c83f72b59dff628a8" dependencies = [ "cobs", "serde", ] [[package]] name = "proc-macro2" version = "1.0.93" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "60946a68e5f9d28b0dc1c21bb8a97ee7d018a8b322fa57838ba31cc878e22d99" dependencies = [ "unicode-ident", ] [[package]] name = "quote" version = "1.0.38" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0e4dccaaaf89514f546c693ddc140f729f958c247918a13380cccc6078391acc" dependencies = [ "proc-macro2", ] [[package]] name = "serde" version = "1.0.218" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "e8dfc9d19bdbf6d17e22319da49161d5d0108e4188e8b680aef6299eed22df60" dependencies = [ "serde_derive", ] [[package]] name = "serde_derive" version = "1.0.218" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f09503e191f4e797cb8aac08e9a4a4695c5edf6a2e70e376d961ddd5c969f82b" dependencies = [ "proc-macro2", "quote", "syn", ] [[package]] name = "stable_deref_trait" version = "1.2.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a8f112729512f8e442d81f95a8a7ddf2b7c6b8a1a6f509a95864142b30cab2d3" [[package]] name = "syn" version = "2.0.98" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "36147f1a48ae0ec2b5b3bc5b537d267457555a10dc06f3dbc8cb11ba3006d3b1" dependencies = [ "proc-macro2", "quote", "unicode-ident", ] [[package]] name = "synstructure" version = "0.13.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c8af7666ab7b6390ab78131fb5b0fce11d6b7a6951602017c35fa82800708971" dependencies = [ "proc-macro2", "quote", "syn", ] [[package]] name = "unicode-ident" version = "1.0.17" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "00e2473a93778eb0bad35909dff6a10d28e63f792f16ed15e404fca9d5eeedbe" [[package]] name = "yoke" version = "0.8.0" dependencies = [ "bincode", "postcard", "serde", "stable_deref_trait", "yoke-derive", "zerofrom", ] [[package]] name = "yoke-derive" version = "0.8.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "38da3c9736e16c5d3c8c597a9aaa5d1fa565d0532ae05e27c24aa62fb32c0ab6" dependencies = [ "proc-macro2", "quote", "syn", "synstructure", ] [[package]] name = "zerofrom" version = "0.1.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "cff3ee08c995dee1859d998dea82f7374f2826091dd9cd47def953cae446cd2e" dependencies = [ "zerofrom-derive", ] [[package]] name = "zerofrom-derive" version = "0.1.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "595eed982f7d355beb85837f651fa22e90b3c044842dc7f2c2842c086f295808" dependencies = [ "proc-macro2", "quote", "syn", "synstructure", ] yoke-0.8.0/Cargo.toml0000644000000044520000000000100100130ustar # 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.81" name = "yoke" version = "0.8.0" authors = ["Manish Goregaokar "] build = false include = [ "data/**/*", "src/**/*", "examples/**/*", "benches/**/*", "tests/**/*", "Cargo.toml", "LICENSE", "README.md", ] autolib = false autobins = false autoexamples = false autotests = false autobenches = false 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 = "Unicode-3.0" 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 [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"] [lib] name = "yoke" path = "src/lib.rs" [[test]] name = "bincode" path = "tests/bincode.rs" [[test]] name = "miri" path = "tests/miri.rs" [dependencies.serde] version = "1.0.110" optional = true default-features = false [dependencies.stable_deref_trait] version = "1.2.0" default-features = false [dependencies.yoke-derive] version = "0.8.0" optional = true default-features = false [dependencies.zerofrom] version = "0.1.3" optional = true default-features = false [dev-dependencies.bincode] version = "1.3.1" [dev-dependencies.postcard] version = "1.0.3" default-features = false [dev-dependencies.serde] version = "1.0.110" default-features = false yoke-0.8.0/Cargo.toml.orig000064400000000000000000000026621046102023000134750ustar 00000000000000# 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 ). [package] name = "yoke" description = "Abstraction allowing borrowed data to be carried along with the backing data it borrows from" version = "0.8.0" authors = ["Manish Goregaokar "] categories = ["data-structures", "memory-management", "caching", "no-std"] keywords = ["zerocopy", "serialization", "lifetime", "borrow", "self-referential"] edition.workspace = true include.workspace = true license.workspace = true repository.workspace = true rust-version.workspace = true [package.metadata.workspaces] independent = true [features] default = ["alloc", "zerofrom"] derive = ["dep:yoke-derive", "zerofrom/derive"] alloc = ["stable_deref_trait/alloc", "serde?/alloc", "zerofrom/alloc"] serde = ["dep:serde"] zerofrom = ["dep:zerofrom"] [package.metadata.docs.rs] all-features = true [package.metadata.cargo-all-features] # We have tons of features here, limit the amount of tests we run max_combination_size = 3 [dependencies] stable_deref_trait = { workspace = true } yoke-derive = { workspace = true, optional = true } serde = { workspace = true, optional = true } zerofrom = { workspace = true, optional = true} [dev-dependencies] bincode = { workspace = true } postcard = { workspace = true } serde = { workspace = true } yoke-0.8.0/LICENSE000064400000000000000000000042231046102023000116060ustar 00000000000000UNICODE LICENSE V3 COPYRIGHT AND PERMISSION NOTICE Copyright © 2020-2024 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. SPDX-License-Identifier: Unicode-3.0 — 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. yoke-0.8.0/README.md000064400000000000000000000035271046102023000120660ustar 00000000000000# 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). yoke-0.8.0/src/cartable_ptr.rs000064400000000000000000000342761046102023000144130ustar 00000000000000// 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 for optional pointers with niche optimization. //! //! The main type is [`CartableOptionPointer`], which is like `Option` but //! with a niche so that the resulting `Yoke` has a niche. The following four //! types can be stored in the `CartableOptionPointer`: //! //! 1. `&T` //! 2. `Box` //! 3. `Rc` //! 4. `Arc` //! //! These four types implement the sealed unsafe trait [`CartablePointerLike`]. //! In addition, all except `Box` impl [`CloneableCartablePointerLike`], //! which allows [`CartableOptionPointer`] to implement `Clone`. use crate::CloneableCart; #[cfg(feature = "alloc")] use alloc::boxed::Box; #[cfg(feature = "alloc")] use alloc::rc::Rc; #[cfg(feature = "alloc")] use alloc::sync::Arc; #[cfg(test)] use core::cell::Cell; use core::marker::PhantomData; use core::ptr::NonNull; use stable_deref_trait::StableDeref; // Safety note: this method MUST return the same value for the same T, even if i.e. the method gets // instantiated in different crates. This can be untrue in surprising ways! For example, just // returning a const-ref-to-const would not guarantee that. // The current implementation always returns the same address for any T, see // [the reference](https://doc.rust-lang.org/reference/items/static-items.html#statics--generics): // there is exactly one `SENTINEL` item for any T. #[inline] fn sentinel_for() -> NonNull { static SENTINEL: &u8 = &0x1a; // SUB // Safety: SENTINEL is indeed not a null pointer, even after the casts. unsafe { NonNull::new_unchecked(SENTINEL as *const u8 as *mut T) } } #[cfg(test)] thread_local! { static DROP_INVOCATIONS: Cell = const { Cell::new(0) }; } mod private { pub trait Sealed {} } use private::Sealed; /// An object fully representable by a non-null pointer. /// /// # Safety /// /// Implementer safety: /// /// 1. `into_raw` transfers ownership of the values referenced by StableDeref to the caller, /// if there is ownership to transfer /// 2. `drop_raw` returns ownership back to the impl, if there is ownership to transfer /// /// Note: if `into_raw` returns the sentinel pointer, memory leaks may occur, but this will not /// lead to undefined behaviour. /// /// Note: the pointer `NonNull` may or may not be aligned and it should never /// be dereferenced. Rust allows unaligned pointers; see [`std::ptr::read_unaligned`]. pub unsafe trait CartablePointerLike: StableDeref + Sealed { /// The raw type used for [`Self::into_raw`] and [`Self::drop_raw`]. #[doc(hidden)] type Raw; /// Converts this pointer-like into a pointer. #[doc(hidden)] fn into_raw(self) -> NonNull; /// Drops any memory associated with this pointer-like. /// /// # Safety /// /// Caller safety: /// /// 1. The pointer MUST have been returned by this impl's `into_raw`. /// 2. The pointer MUST NOT be dangling. #[doc(hidden)] unsafe fn drop_raw(pointer: NonNull); } /// An object that implements [`CartablePointerLike`] that also /// supports cloning without changing the address of referenced data. /// /// # Safety /// /// Implementer safety: /// /// 1. `addref_raw` must create a new owner such that an additional call to /// `drop_raw` does not create a dangling pointer /// 2. `addref_raw` must not change the address of any referenced data. pub unsafe trait CloneableCartablePointerLike: CartablePointerLike { /// Clones this pointer-like. /// /// # Safety /// /// Caller safety: /// /// 1. The pointer MUST have been returned by this impl's `into_raw`. /// 2. The pointer MUST NOT be dangling. #[doc(hidden)] unsafe fn addref_raw(pointer: NonNull); } impl<'a, T> Sealed for &'a T {} // Safety: // 1. There is no ownership to transfer // 2. There is no ownership to transfer unsafe impl<'a, T> CartablePointerLike for &'a T { type Raw = T; #[inline] fn into_raw(self) -> NonNull { self.into() } #[inline] unsafe fn drop_raw(_pointer: NonNull) { // No-op: references are borrowed from elsewhere } } // Safety: // 1. There is no ownership // 2. The impl is a no-op so no addresses are changed. unsafe impl<'a, T> CloneableCartablePointerLike for &'a T { #[inline] unsafe fn addref_raw(_pointer: NonNull) { // No-op: references are borrowed from elsewhere } } #[cfg(feature = "alloc")] impl Sealed for Box {} #[cfg(feature = "alloc")] // Safety: // 1. `Box::into_raw` says: "After calling this function, the caller is responsible for the // memory previously managed by the Box." // 2. `Box::from_raw` says: "After calling this function, the raw pointer is owned by the // resulting Box." unsafe impl CartablePointerLike for Box { type Raw = T; #[inline] fn into_raw(self) -> NonNull { // Safety: `Box::into_raw` says: "The pointer will be properly aligned and non-null." unsafe { NonNull::new_unchecked(Box::into_raw(self)) } } #[inline] unsafe fn drop_raw(pointer: NonNull) { // Safety: per the method's precondition, `pointer` is dereferenceable and was returned by // `Self::into_raw`, i.e. by `Box::into_raw`. In this circumstances, calling // `Box::from_raw` is safe. let _box = unsafe { Box::from_raw(pointer.as_ptr()) }; // Boxes are always dropped #[cfg(test)] DROP_INVOCATIONS.with(|x| x.set(x.get() + 1)) } } #[cfg(feature = "alloc")] impl Sealed for Rc {} #[cfg(feature = "alloc")] // Safety: // 1. `Rc::into_raw` says: "Consumes the Rc, returning the wrapped pointer. To avoid a memory // leak the pointer must be converted back to an Rc using Rc::from_raw." // 2. See 1. unsafe impl CartablePointerLike for Rc { type Raw = T; #[inline] fn into_raw(self) -> NonNull { // Safety: Rcs must contain data (and not be null) unsafe { NonNull::new_unchecked(Rc::into_raw(self) as *mut T) } } #[inline] unsafe fn drop_raw(pointer: NonNull) { // Safety: per the method's precondition, `pointer` is dereferenceable and was returned by // `Self::into_raw`, i.e. by `Rc::into_raw`. In this circumstances, calling // `Rc::from_raw` is safe. let _rc = unsafe { Rc::from_raw(pointer.as_ptr()) }; // Rc is dropped if refcount is 1 #[cfg(test)] if Rc::strong_count(&_rc) == 1 { DROP_INVOCATIONS.with(|x| x.set(x.get() + 1)) } } } #[cfg(feature = "alloc")] // Safety: // 1. The impl increases the refcount such that `Drop` will decrease it. // 2. The impl increases refcount without changing the address of data. unsafe impl CloneableCartablePointerLike for Rc { #[inline] unsafe fn addref_raw(pointer: NonNull) { // Safety: The caller safety of this function says that: // 1. The pointer was obtained through Rc::into_raw // 2. The associated Rc instance is valid // Further, this impl is not defined for anything but the global allocator. unsafe { Rc::increment_strong_count(pointer.as_ptr()); } } } #[cfg(feature = "alloc")] impl Sealed for Arc {} #[cfg(feature = "alloc")] // Safety: // 1. `Rc::into_raw` says: "Consumes the Arc, returning the wrapped pointer. To avoid a memory // leak the pointer must be converted back to an Arc using Arc::from_raw." // 2. See 1. unsafe impl CartablePointerLike for Arc { type Raw = T; #[inline] fn into_raw(self) -> NonNull { // Safety: Arcs must contain data (and not be null) unsafe { NonNull::new_unchecked(Arc::into_raw(self) as *mut T) } } #[inline] unsafe fn drop_raw(pointer: NonNull) { // Safety: per the method's precondition, `pointer` is dereferenceable and was returned by // `Self::into_raw`, i.e. by `Rc::into_raw`. In this circumstances, calling // `Rc::from_raw` is safe. let _arc = unsafe { Arc::from_raw(pointer.as_ptr()) }; // Arc is dropped if refcount is 1 #[cfg(test)] if Arc::strong_count(&_arc) == 1 { DROP_INVOCATIONS.with(|x| x.set(x.get() + 1)) } } } #[cfg(feature = "alloc")] // Safety: // 1. The impl increases the refcount such that `Drop` will decrease it. // 2. The impl increases refcount without changing the address of data. unsafe impl CloneableCartablePointerLike for Arc { #[inline] unsafe fn addref_raw(pointer: NonNull) { // Safety: The caller safety of this function says that: // 1. The pointer was obtained through Arc::into_raw // 2. The associated Arc instance is valid // Further, this impl is not defined for anything but the global allocator. unsafe { Arc::increment_strong_count(pointer.as_ptr()); } } } /// A type with similar semantics as `Option>` but with a niche. /// /// This type cannot be publicly constructed. To use this in a `Yoke`, see /// [`Yoke::convert_cart_into_option_pointer`]. /// /// [`Yoke::convert_cart_into_option_pointer`]: crate::Yoke::convert_cart_into_option_pointer #[derive(Debug)] pub struct CartableOptionPointer where C: CartablePointerLike, { /// The inner pointer. /// /// # Invariants /// /// 1. Must be either `SENTINEL_PTR` or created from `CartablePointerLike::into_raw` /// 2. If non-sentinel, must _always_ be for a valid SelectedRc inner: NonNull, _cartable: PhantomData, } impl CartableOptionPointer where C: CartablePointerLike, { /// Creates a new instance corresponding to a `None` value. #[inline] pub(crate) fn none() -> Self { Self { inner: sentinel_for::(), _cartable: PhantomData, } } /// Creates a new instance corresponding to a `Some` value. #[inline] pub(crate) fn from_cartable(cartable: C) -> Self { let inner = cartable.into_raw(); debug_assert_ne!(inner, sentinel_for::()); Self { inner, _cartable: PhantomData, } } /// Returns whether this instance is `None`. From the return value: /// /// - If `true`, the instance is `None` /// - If `false`, the instance is a valid `SelectedRc` #[inline] pub fn is_none(&self) -> bool { self.inner == sentinel_for::() } } impl Drop for CartableOptionPointer where C: CartablePointerLike, { #[inline] fn drop(&mut self) { let ptr = self.inner; if ptr != sentinel_for::() { // By the invariants, `ptr` is a valid raw value since it's // either that or sentinel, and we just checked for sentinel. // We will replace it with the sentinel and then drop `ptr`. self.inner = sentinel_for::(); // Safety: by the invariants, `ptr` is a valid raw value. unsafe { C::drop_raw(ptr) } } } } impl Clone for CartableOptionPointer where C: CloneableCartablePointerLike, { #[inline] fn clone(&self) -> Self { let ptr = self.inner; if ptr != sentinel_for::() { // By the invariants, `ptr` is a valid raw value since it's // either that or sentinel, and we just checked for sentinel. // Safety: by the invariants, `ptr` is a valid raw value. unsafe { C::addref_raw(ptr) } } Self { inner: self.inner, _cartable: PhantomData, } } } // Safety: logically an Option. Has same bounds as Option. // The `StableDeref` parts of `C` continue to be `StableDeref`. unsafe impl CloneableCart for CartableOptionPointer where C: CloneableCartablePointerLike + CloneableCart { } // Safety: logically an Option. Has same bounds as Option unsafe impl Send for CartableOptionPointer where C: Sync + CartablePointerLike {} // Safety: logically an Option. Has same bounds as Option unsafe impl Sync for CartableOptionPointer where C: Send + CartablePointerLike {} #[cfg(test)] mod tests { use super::*; use crate::Yoke; use core::mem::size_of; const SAMPLE_BYTES: &[u8] = b"abCDEfg"; const W: usize = size_of::(); #[test] fn test_sizes() { assert_eq!(W * 4, size_of::>()); assert_eq!(W * 4, size_of::>>()); assert_eq!( W * 4, size_of::>>() ); assert_eq!(W * 4, size_of::>>()); assert_eq!(W * 5, size_of::>>>()); assert_eq!( W * 4, size_of::>>>() ); } #[test] fn test_new_sentinel() { let start = DROP_INVOCATIONS.with(Cell::get); { let _ = CartableOptionPointer::>::none(); } assert_eq!(start, DROP_INVOCATIONS.with(Cell::get)); { let _ = CartableOptionPointer::>::none(); } assert_eq!(start, DROP_INVOCATIONS.with(Cell::get)); } #[test] fn test_new_rc() { let start = DROP_INVOCATIONS.with(Cell::get); { let _ = CartableOptionPointer::>::from_cartable(SAMPLE_BYTES.into()); } assert_eq!(start + 1, DROP_INVOCATIONS.with(Cell::get)); } #[test] fn test_rc_clone() { let start = DROP_INVOCATIONS.with(Cell::get); { let x = CartableOptionPointer::>::from_cartable(SAMPLE_BYTES.into()); assert_eq!(start, DROP_INVOCATIONS.with(Cell::get)); { let _ = x.clone(); } assert_eq!(start, DROP_INVOCATIONS.with(Cell::get)); { let _ = x.clone(); let _ = x.clone(); let _ = x.clone(); } assert_eq!(start, DROP_INVOCATIONS.with(Cell::get)); } assert_eq!(start + 1, DROP_INVOCATIONS.with(Cell::get)); } } yoke-0.8.0/src/either.rs000064400000000000000000000050341046102023000132170ustar 00000000000000// 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::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, T: ?Sized, { type Target = T; fn deref(&self) -> &T { use EitherCart::*; match self { A(a) => a.deref(), B(b) => b.deref(), } } } // Safety: Safe because both sub-types implement the trait. unsafe impl StableDeref for EitherCart where C0: StableDeref, C1: StableDeref, C0: Deref, C1: Deref, T: ?Sized, { } // Safety: Safe because both sub-types implement the trait. unsafe impl CloneableCart for EitherCart where C0: CloneableCart, C1: CloneableCart, { } yoke-0.8.0/src/erased.rs000064400000000000000000000031661046102023000132060ustar 00000000000000// 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; yoke-0.8.0/src/kinda_sorta_dangling.rs000064400000000000000000000101271046102023000160770ustar 00000000000000// 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 under miri's field-retagging mode if not using /// KindaSortaDangling. /// /// 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: Due to the safety invariant on `dangle`, it is guaranteed to be always // initialized as deref is never called during drop. unsafe { self.dangle.assume_init_ref() } } } impl DerefMut for KindaSortaDangling { #[inline] fn deref_mut(&mut self) -> &mut T { // Safety: Due to the safety invariant on `dangle`, it is guaranteed to be always // initialized as deref_mut is never called during drop. unsafe { self.dangle.assume_init_mut() } } } impl Drop for KindaSortaDangling { #[inline] fn drop(&mut self) { // 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. unsafe { self.dangle.as_mut_ptr().drop_in_place(); } } } yoke-0.8.0/src/lib.rs000064400000000000000000000055221046102023000125070ustar 00000000000000// 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/documents/process/boilerplate.md#library-annotations #![cfg_attr(not(any(test, 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, clippy::trivially_copy_pass_by_ref, 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 cartable_ptr; pub mod either; #[cfg(feature = "alloc")] pub mod erased; mod kinda_sorta_dangling; mod macro_impls; 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; yoke-0.8.0/src/macro_impls.rs000064400000000000000000000104771046102023000142530ustar 00000000000000// 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::{self, ManuallyDrop}, 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:ty) => { // Safety: all the types that this macro is used to generate impls of Yokeable for do not // borrow any memory. unsafe impl<'a> Yokeable<'a> for $ty { type Output = Self; copy_yoke_impl!(); } }; } impl_copy_type!(()); 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 // // Safety: the caller of this macro must ensure that `Self` is indeed covariant in 'a. macro_rules! unsafe_complex_yoke_impl { () => { fn transform(&'a self) -> &'a Self::Output { // Safety: equivalent to casting the lifetime. Macro caller ensures covariance. unsafe { mem::transmute(self) } } fn transform_owned(self) -> Self::Output { debug_assert!(mem::size_of::() == mem::size_of::()); // Safety: equivalent to casting the lifetime. Macro caller ensures covariance. unsafe { let ptr: *const Self::Output = (&self as *const Self).cast(); let _ = ManuallyDrop::new(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(); let _ = ManuallyDrop::new(from); // Safety: `ptr` is certainly valid, aligned and points to a properly initialized value, as // it comes from a value that was moved into a ManuallyDrop. unsafe { 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 // Safety: this is equivalent to f(transmute(self)), and the documentation of the trait // method explains why doing so is sound. unsafe { f(mem::transmute::<&'a mut Self, &'a mut Self::Output>(self)) } } }; } // Safety: since T implements Yokeable<'a>, Option> must be covariant on 'b or the Yokeable // implementation on T would be unsound. unsafe impl<'a, T: 'static + for<'b> Yokeable<'b>> Yokeable<'a> for Option { type Output = Option<>::Output>; unsafe_complex_yoke_impl!(); } // Safety: since T1, T2 implement Yokeable<'a>, (T1<'b>, T2<'b>) must be covariant on 'b or the Yokeable // implementation on T would be unsound. 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!(); } // Safety: since T implements Yokeable<'a>, [T<'b>; N] must be covariant on 'b or the Yokeable // implementation on T would be unsound. unsafe impl<'a, T: 'static + for<'b> Yokeable<'b>, const N: usize> Yokeable<'a> for [T; N] { type Output = [>::Output; N]; unsafe_complex_yoke_impl!(); } yoke-0.8.0/src/yoke.rs000064400000000000000000001676531046102023000127260ustar 00000000000000// 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::cartable_ptr::{CartableOptionPointer, CartablePointerLike}; use crate::either::EitherCart; #[cfg(feature = "alloc")] use crate::erased::{ErasedArcCart, ErasedBoxCart, ErasedRcCart}; use crate::kinda_sorta_dangling::KindaSortaDangling; 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; /// # 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, // Safety invariant: this type can be anything, but `yokeable` may only contain references to // StableDeref parts of this cart, and the targets of those references must be valid for the // lifetime of this cart (it must own or borrow them). It's ok for this cart to contain stack // data as long as it is not referenced by `yokeable` during construction. `attach_to_cart`, // the typical constructor of this type, upholds this invariant, but other constructors like // `replace_cart` need to uphold it. // The implementation guarantees that there are no live `yokeable`s that reference data // in a `cart` when the `cart` is dropped; this is guaranteed in the drop glue through field // order. 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. /// /// The closure can read and write data outside of its scope, but data it returns /// may borrow only from the argument passed to the 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; /// # 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(_))); /// ``` /// /// Write the number of consumed bytes to a local variable: /// /// ``` /// # use yoke::Yoke; /// # use std::rc::Rc; /// # use std::borrow::Cow; /// # fn load_from_cache(_filename: &str) -> Rc<[u8]> { /// # // dummy implementation /// # Rc::new([0x5, 0x68, 0x65, 0x6c, 0x6c, 0x6f, 0, 0, 0]) /// # } /// /// fn load_object( /// filename: &str, /// ) -> (Yoke, Rc<[u8]>>, usize) { /// let rc: Rc<[u8]> = load_from_cache(filename); /// let mut bytes_remaining = 0; /// let bytes_remaining = &mut bytes_remaining; /// let yoke = Yoke::, Rc<[u8]>>::attach_to_cart( /// rc, /// |data: &[u8]| { /// let mut d = postcard::Deserializer::from_bytes(data); /// let output = serde::Deserialize::deserialize(&mut d); /// *bytes_remaining = d.finalize().unwrap().len(); /// Cow::Borrowed(output.unwrap()) /// }, /// ); /// (yoke, *bytes_remaining) /// } /// /// let (yoke, bytes_remaining) = load_object("filename.postcard"); /// assert_eq!(&**yoke.get(), "hello"); /// assert!(matches!(yoke.get(), &Cow::Borrowed(_))); /// assert_eq!(bytes_remaining, 3); /// ``` 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( // Safety: the resulting `yokeable` is dropped before the `cart` because // of the Yoke invariant. See the safety docs at the bottom of this file // for the justification of why yokeable could only borrow from the Cart. 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>, ::Target: 'static, { let deserialized = f(cart.deref())?; Ok(Self { yokeable: KindaSortaDangling::new( // Safety: the resulting `yokeable` is dropped before the `cart` because // of the Yoke invariant. See the safety docs at the bottom of this file // for the justification of why yokeable could only borrow from the Cart. 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; /// # 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`. /// /// For the purpose of determining this, `Yoke` guarantees that references from the Yokeable /// `Y` into the cart `C` will never be references into its stack data, only heap data protected /// by `StableDeref`. This does not necessarily mean that `C` implements `StableDeref`, rather that /// any data referenced by `Y` must be accessed through a `StableDeref` impl on something `C` owns. /// /// Concretely, this means that if `C = Option>`, `Y` may contain references to the `T` but not /// anything else. /// - 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 { // Safety note: the safety invariant of this function guarantees that // the data that the yokeable references has its ownership (if any) // transferred to the new cart before self.cart is dropped. 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> { // Safety: the cart is preserved (since it is just wrapped into a Some), // so any data it owns is too. unsafe { 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; /// /// 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 { // Safety note: this `yokeable` certainly does not reference data owned by (), so we do // not have to worry about when the `yokeable` is dropped. 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 { // Safety note: since `yokeable` cannot reference data owned by `()`, this is certainly // safe. self.yokeable.into_inner() } } // C does not need to be StableDeref here, if the yoke was constructed it's valid, // and new_owned() doesn't construct a yokeable that uses references, impl Yokeable<'a>, C> 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 { // Safety note: this `yokeable` is known not to borrow from the cart. yokeable: KindaSortaDangling::new(yokeable), cart: None, } } /// Obtain the yokeable out of a `Yoke>` if possible. /// /// If the cart is `None`, this returns `Ok`, but if the cart is `Some`, /// this returns `self` as an error. pub fn try_into_yokeable(self) -> Result { // Safety: if the cart is None there is no way for the yokeable to // have references into it because of the cart invariant. match self.cart { Some(_) => Err(self), None => Ok(self.yokeable.into_inner()), } } } impl Yokeable<'a>, C: CartablePointerLike> Yoke> { /// Converts a `Yoke>` to `Yoke>` /// for better niche optimization when stored as a field. /// /// # Examples /// /// ``` /// use std::borrow::Cow; /// use yoke::Yoke; /// /// let yoke: Yoke, Box>> = /// Yoke::attach_to_cart(vec![10, 20, 30].into(), |c| c.into()); /// /// let yoke_option = yoke.wrap_cart_in_option(); /// let yoke_option_pointer = yoke_option.convert_cart_into_option_pointer(); /// ``` /// /// The niche improves stack sizes: /// /// ``` /// use yoke::Yoke; /// use yoke::cartable_ptr::CartableOptionPointer; /// use std::mem::size_of; /// use std::rc::Rc; /// /// // The data struct is 6 words: /// # #[derive(yoke::Yokeable)] /// # struct MyDataStruct<'a> { /// # _s: (usize, usize, usize, usize), /// # _p: &'a str, /// # } /// const W: usize = core::mem::size_of::(); /// assert_eq!(W * 6, size_of::()); /// /// // An enum containing the data struct with an `Option` cart is 8 words: /// enum StaticOrYoke1 { /// Static(&'static MyDataStruct<'static>), /// Yoke(Yoke, Option>>), /// } /// assert_eq!(W * 8, size_of::()); /// /// // When using `CartableOptionPointer``, we need only 7 words for the same behavior: /// enum StaticOrYoke2 { /// Static(&'static MyDataStruct<'static>), /// Yoke(Yoke, CartableOptionPointer>>), /// } /// assert_eq!(W * 7, size_of::()); /// ``` #[inline] pub fn convert_cart_into_option_pointer(self) -> Yoke> { match self.cart { Some(cart) => Yoke { // Safety note: CartableOptionPointer::from_cartable only wraps the `cart`, // so the data referenced by the yokeable is still live. yokeable: self.yokeable, cart: CartableOptionPointer::from_cartable(cart), }, None => Yoke { // Safety note: this Yokeable cannot refer to any data since self.cart is None. yokeable: self.yokeable, cart: CartableOptionPointer::none(), }, } } } impl Yokeable<'a>, C: CartablePointerLike> Yoke> { /// Obtain the yokeable out of a `Yoke>` if possible. /// /// If the cart is `None`, this returns `Ok`, but if the cart is `Some`, /// this returns `self` as an error. #[inline] pub fn try_into_yokeable(self) -> Result { if self.cart.is_none() { Ok(self.yokeable.into_inner()) } else { Err(self) } } } /// 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 on `StableDeref` types which, once `Clone`d, point to the same underlying data and retain ownership. /// /// This trait can also be implemented on aggregates of such types like `Option` and `(T: CloneableCart, U: CloneableCart)`. /// /// Essentially, all data that could be referenced by a Yokeable (i.e. data that is referenced via a StableDeref) must retain the same /// pointer and ownership semantics once cloned. pub unsafe trait CloneableCart: Clone {} #[cfg(feature = "alloc")] // Safety: Rc implements CloneStableDeref. unsafe impl CloneableCart for Rc {} #[cfg(feature = "alloc")] // Safety: Arc implements CloneStableDeref. unsafe impl CloneableCart for Arc {} // Safety: Option cannot deref to anything that T doesn't already deref to. unsafe impl CloneableCart for Option {} // Safety: &'a T is indeed StableDeref, and cloning it refers to the same data. // &'a T does not own in the first place, so ownership is preserved. unsafe impl<'a, T: ?Sized> CloneableCart for &'a T {} // Safety: () cannot deref to anything. 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> >::Output: Clone, { fn clone(&self) -> Self { // We have an &T not a T, and we can clone T let this = self.get().clone(); Yoke { yokeable: KindaSortaDangling::new( // Safety: C being a CloneableCart guarantees that the data referenced by the // `yokeable` is kept alive by the clone of the cart. unsafe { Y::make(this) }, ), 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 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 at the end of the file. 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( // Safety: the resulting `yokeable` is dropped before the `cart` because // of the Yoke invariant. See the safety docs below for the justification of why // yokeable could only borrow from the Cart. 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( // Safety: the resulting `yokeable` is dropped before the `cart` because // of the Yoke invariant. See the safety docs below for the justification of why // yokeable could only borrow from the Cart. 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 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( // Safety: the resulting `yokeable` is dropped before the `cart` because // of the Yoke invariant. See the safety docs below for the justification of why // yokeable could only borrow from the Cart. 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( // Safety: the resulting `yokeable` is dropped before the `cart` because // of the Yoke invariant. See the safety docs below for the justification of why // yokeable could only borrow from the Cart. 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( // Safety: the resulting `yokeable` is dropped before the `cart` because // of the Yoke invariant. See the safety docs below for the justification of why // yokeable could only borrow from the Cart. 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( // Safety: the resulting `yokeable` is dropped before the `cart` because // of the Yoke invariant. See the safety docs below for the justification of why // yokeable could only borrow from the Cart. 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( // Safety: the resulting `yokeable` is dropped before the `cart` because // of the Yoke invariant. See the safety docs below for the justification of why // yokeable could only borrow from the Cart. 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( // Safety: the resulting `yokeable` is dropped before the `cart` because // of the Yoke invariant. See the safety docs below for the justification of why // yokeable could only borrow from the Cart. 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 { // Safety: safe because the cart is preserved, as it is just type-erased unsafe { 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 { // Safety: safe because the cart is preserved, as it is just type-erased unsafe { 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 { // Safety: safe because the cart is preserved, as it is just type-erased unsafe { 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> { // Safety: safe because the cart is preserved, as it is just wrapped. unsafe { 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> { // Safety: safe because the cart is preserved, as it is just wrapped unsafe { 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> { // Safety: safe because the cart is preserved, as it is just wrapped unsafe { 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> { // Safety: safe because the cart is preserved, as it is just wrapped. unsafe { 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> { // Safety: safe because the cart is preserved, as it is just wrapped. unsafe { 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`. /// /// Note that correctness arguments are similar if you replace `fn` with `FnOnce`. /// /// 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; /// /// 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; /// /// 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; /// // 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 _: () = (); yoke-0.8.0/src/yokeable.rs000064400000000000000000000335271046102023000135420ustar 00000000000000// 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::{marker::PhantomData, 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>`. /// /// This trait is also safe to implement on types that do not borrow memory. /// /// There are further constraints on implementation safety on individual methods. /// /// # 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')); /// } /// ``` /// /// More formally, a reference to an object that `f` assigns to a reference /// in Self<'a> could be obtained from: /// - a local variable: the compiler rejects the assignment because 'a certainly /// outlives local variables in f. /// - a field in its argument: because of the for<'b> bound, the call to `f` /// must be valid for a particular 'b that is strictly shorter than 'a. Thus, /// the compiler rejects the assignment. /// - a reference field in Self<'a>: this does not extend the set of /// non-static lifetimes reachable from Self<'a>, so this is fine. /// - one of f's captures: since F: 'static, the resulting reference must refer /// to 'static data. /// - a static or thread_local variable: ditto. 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")] // Safety: Cow<'a, _> is covariant in 'a. 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(); let _ = core::mem::ManuallyDrop::new(from); // Safety: `ptr` is certainly valid, aligned and points to a properly initialized value, as // it comes from a value that was moved into a ManuallyDrop. unsafe { 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 // Safety: this is equivalent to f(transmute(self)), and the documentation of the trait // method explains why doing so is sound. unsafe { f(mem::transmute::<&'a mut Self, &'a mut Self::Output>(self)) } } } // Safety: &'a T is covariant in 'a. 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 { // Safety: function safety invariant guarantees that the returned reference // will never be used beyond its original lifetime. unsafe { 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 // Safety: this is equivalent to f(transmute(self)), and the documentation of the trait // method explains why doing so is sound. unsafe { f(mem::transmute::<&'a mut Self, &'a mut Self::Output>(self)) } } } #[cfg(feature = "alloc")] // Safety: Vec never borrows. 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 { self } #[inline] fn transform_owned(self) -> alloc::vec::Vec { 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), { f(self) } } // Safety: PhantomData is a ZST. unsafe impl<'a, T: ?Sized + 'static> Yokeable<'a> for PhantomData { type Output = PhantomData; fn transform(&'a self) -> &'a Self::Output { self } fn transform_owned(self) -> Self::Output { self } unsafe fn make(from: Self::Output) -> Self { from } 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), { f(self) } } yoke-0.8.0/src/zero_from.rs000064400000000000000000000025551046102023000137460ustar 00000000000000// 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::Yoke; use crate::Yokeable; use core::ops::Deref; use stable_deref_trait::StableDeref; use crate::ZeroFrom; impl Yoke where Y: for<'a> Yokeable<'a>, for<'a> >::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| ::Output::zero_from(c)) } } yoke-0.8.0/tests/bincode.rs000064400000000000000000000051001046102023000137070ustar 00000000000000// 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::<&mut Bar<'_>, &mut Bar<'a>>(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(_))); } yoke-0.8.0/tests/miri.rs000064400000000000000000000007551046102023000132570ustar 00000000000000// 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)); }