1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325
// This file is part of ICU4X. For terms of use, please see the file
// called LICENSE at the top level of the ICU4X source tree
// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).
#[cfg(feature = "alloc")]
use alloc::borrow::{Cow, ToOwned};
use core::mem;
/// The `Yokeable<'a>` trait is implemented on the `'static` version of any zero-copy type; for
/// example, `Cow<'static, T>` implements `Yokeable<'a>` (for all `'a`). One can use
/// `Yokeable::Output` on this trait to obtain the "lifetime'd" value of the `Cow<'static, T>`,
/// e.g. `<Cow<'static, T> as Yokeable<'a>'>::Output` is `Cow<'a, T>`.
///
/// A [`Yokeable`] type is essentially one with a covariant lifetime parameter,
/// matched to the parameter in the trait definition. The trait allows one to cast
/// the covariant lifetime to and from `'static`.
///
/// **Most of the time, if you need to implement [`Yokeable`], you should be able to use the safe
/// [`#[derive(Yokeable)]`](yoke_derive::Yokeable) custom derive.**
///
/// While Rust does not yet have GAT syntax, for the purpose of this documentation
/// we shall refer to "`Self` with a lifetime `'a`" with the syntax `Self<'a>`.
/// Self<'static> is a stand-in for the HKT Self<'_>: lifetime -> type.
///
/// With this terminology, [`Yokeable`] exposes ways to cast between `Self<'static>` and `Self<'a>` generically.
/// This is useful for turning covariant lifetimes to _dynamic_ lifetimes, where `'static` is
/// used as a way to "erase" the lifetime.
///
/// # Safety
///
/// This trait is safe to implement on types with a _covariant_ lifetime parameter, i.e. one where
/// [`Self::transform()`]'s body can simply be `{ self }`. This will occur when the lifetime
/// parameter is used within references, but not in the arguments of function pointers or in mutable
/// positions (either in `&mut` or via interior mutability)
///
/// This trait must be implemented on the `'static` version of such a type, e.g. one should
/// implement `Yokeable<'a>` (for all `'a`) on `Cow<'static, T>`.
///
/// There are further constraints on implementation safety on individual methods.
///
/// # Trait bounds
///
/// [Compiler bug #85636](https://github.com/rust-lang/rust/issues/85636) makes it tricky to add
/// trait bounds on `Yokeable::Output`. For more information and for workarounds, see
/// [`crate::trait_hack`].
///
/// # Implementation example
///
/// Implementing this trait manually is unsafe. Where possible, you should use the safe
/// [`#[derive(Yokeable)]`](yoke_derive::Yokeable) custom derive instead. We include an example
/// in case you have your own zero-copy abstractions you wish to make yokeable.
///
/// ```rust
/// # use yoke::Yokeable;
/// # use std::borrow::Cow;
/// # use std::{mem, ptr};
/// struct Bar<'a> {
/// numbers: Cow<'a, [u8]>,
/// string: Cow<'a, str>,
/// owned: Vec<u8>,
/// }
///
/// 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::<Bar<'a>>() == mem::size_of::<Self>());
/// let ptr: *const Self = (&from as *const Self::Output).cast();
/// mem::forget(from);
/// ptr::read(ptr)
/// }
///
/// fn transform_mut<F>(&'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<F>(&'a mut self, f: F)
/// # where
/// # F: 'static + FnOnce(&'a mut Self::Output),
/// # {
/// # unsafe { f(mem::transmute(self)) }
/// # }
/// # }
/// ```
///
/// which is unsound because `bar` could be moved later, and we do not want to be able to
/// self-insert references to it.
///
/// The `for<'b>` enforces this by stopping the author of the closure from matching up the input
/// `&'b Self::Output` lifetime with `'a` and borrowing directly from it.
///
/// Thus the only types of mutations allowed are ones that move around already-borrowed data, or
/// introduce new owned data:
///
/// ```rust
/// # use std::borrow::Cow;
/// # use yoke::Yokeable;
/// struct Foo {
/// str: String,
/// cow: Cow<'static, str>,
/// }
///
/// fn sound<'a>(foo: &'a mut Foo) {
/// foo.cow.transform_mut(move |cow| cow.to_mut().push('a'));
/// }
/// ```
fn transform_mut<F>(&'a mut self, f: F)
where
// be VERY CAREFUL changing this signature, it is very nuanced (see above)
F: 'static + for<'b> FnOnce(&'b mut Self::Output);
}
#[cfg(feature = "alloc")]
unsafe impl<'a, T: 'static + ToOwned + ?Sized> Yokeable<'a> for Cow<'static, T>
where
<T as ToOwned>::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::<Cow<'a, T>>() == mem::size_of::<Self>());
let ptr: *const Self = (&from as *const Self::Output).cast();
mem::forget(from);
core::ptr::read(ptr)
}
#[inline]
fn transform_mut<F>(&'a mut self, f: F)
where
F: 'static + for<'b> FnOnce(&'b mut Self::Output),
{
// Cast away the lifetime of Self
unsafe { f(mem::transmute::<&'a mut Self, &'a mut Self::Output>(self)) }
}
}
unsafe impl<'a, T: 'static + ?Sized> Yokeable<'a> for &'static T {
type Output = &'a T;
#[inline]
fn transform(&'a self) -> &'a &'a T {
// Doesn't need unsafe: `'a` is covariant so this lifetime cast is always safe
self
}
#[inline]
fn transform_owned(self) -> &'a T {
// Doesn't need unsafe: `'a` is covariant so this lifetime cast is always safe
self
}
#[inline]
unsafe fn make(from: &'a T) -> Self {
mem::transmute(from)
}
#[inline]
fn transform_mut<F>(&'a mut self, f: F)
where
F: 'static + for<'b> FnOnce(&'b mut Self::Output),
{
// Cast away the lifetime of Self
unsafe { f(mem::transmute::<&'a mut Self, &'a mut Self::Output>(self)) }
}
}
#[cfg(feature = "alloc")]
unsafe impl<'a, T: 'static> Yokeable<'a> for alloc::vec::Vec<T> {
type Output = alloc::vec::Vec<T>;
#[inline]
fn transform(&'a self) -> &'a alloc::vec::Vec<T> {
// Doesn't need unsafe: `'a` is covariant so this lifetime cast is always safe
self
}
#[inline]
fn transform_owned(self) -> alloc::vec::Vec<T> {
// Doesn't need unsafe: `'a` is covariant so this lifetime cast is always safe
self
}
#[inline]
unsafe fn make(from: alloc::vec::Vec<T>) -> Self {
from
}
#[inline]
fn transform_mut<F>(&'a mut self, f: F)
where
F: 'static + for<'b> FnOnce(&'b mut Self::Output),
{
// Doesn't need unsafe: `'a` is covariant so this lifetime cast is always safe
f(self)
}
}