yoke.rs

// 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::Cart;
use crate::Cartable;
use crate::Yokeable;
use std::rc::Rc;
use std::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.
///
/// `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 erase
/// the lifetime and make it dynamic.
///
/// `C` is the "cart", which `Y` may contain references to. A [`Yoke`] can be constructed
/// with such references using [`Yoke::attach_to_cart()`].
///
/// # Example
///
/// For example, we can use this to store zero-copy deserialized data in a cache:
///
/// TODO this test is broken!
/// ```rust,ignore
/// # use yoke::{Yoke, Yokeable};
/// # use std::rc::Rc;
/// # use std::borrow::Cow;
/// # fn load_from_cache(_filename: &str) -> Rc<[u8]> {
/// #     // dummy implementation
/// #     Rc::new([0x68, 0x65, 0x6c, 0x6c, 0x6f])
/// # }
///
/// fn load_object(filename: &str) -> Yoke<Cow<'static, [u8]>, Rc<[u8]>> {
///     let rc: Rc<[u8]> = load_from_cache(filename);
///     Yoke::<Cow<'static, [u8]>, Rc<[u8]>>::attach_to_cart(rc, |data: &[u8]| {
///         bincode::deserialize_from(data).unwrap();
///     });
/// }
/// ```
///
pub struct Yoke<Y: for<'a> Yokeable<'a>, C: Cart> {
    // must be the first field for drop order
    // this will have a 'static lifetime parameter, that parameter is a lie
    yokeable: Y,
    cart: C,
}

impl<Y: for<'a> Yokeable<'a>, C: Cart> Yoke<Y, C> {
    /// Construct a new [`Yoke`] from static data. There will be no
    /// references to `cart` here, this is good for e.g. constructing fully owned
    /// [`Yoke`]s with no internal borrowing.
    pub fn new(cart: C, yokeable: Y) -> Self {
        Self { yokeable, cart }
    }

    /// 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<Cow<'static, T>, C>`, this
    /// will return an `&'a Cow<'a, T>`
    pub fn get<'a>(&'a self) -> &'a <Y as Yokeable<'a>>::Output {
        self.yokeable.transform()
    }

    /// Get a reference to the backing cart.
    pub fn backing_cart(&self) -> &C {
        &self.cart
    }

    pub fn with_mut<'a, F>(&'a mut self, f: F)
    where
        F: 'static + for<'b> FnOnce(&'b mut <Y as Yokeable<'a>>::Output),
    {
        self.yokeable.with_mut(f)
    }

    pub fn attach_to_cart<F>(cart: C, f: F) -> Self
    where
        F: for<'de> FnOnce(&'de C::Inner) -> (<Y as Yokeable<'de>>::Output),
    {
        let deserialized = f(cart.get_inner());
        Self {
            yokeable: unsafe { Y::make(deserialized) },
            cart,
        }
    }
}

// clone impls only work for reference counted objects, otherwise you should be
// cloning `backing_cart()` and reusing `attach_to_cart()`
impl<Y: for<'a> Yokeable<'a>, T: Cartable + ?Sized> Clone for Yoke<Y, Rc<T>>
where
    for<'a> <Y as Yokeable<'a>>::Output: Clone,
{
    fn clone(&self) -> Self {
        Yoke {
            yokeable: unsafe { Y::make(self.get().clone()) },
            cart: self.cart.clone(),
        }
    }
}

impl<Y: for<'a> Yokeable<'a>, T: Cartable + ?Sized> Clone for Yoke<Y, Arc<T>>
where
    for<'a> <Y as Yokeable<'a>>::Output: Clone,
{
    fn clone(&self) -> Self {
        Yoke {
            yokeable: unsafe { Y::make(self.get().clone()) },
            cart: self.cart.clone(),
        }
    }
}

#[test]
fn this_test_is_broken() {
    use crate::{Yoke, Yokeable};
    use std::borrow::Cow;
    use std::rc::Rc;
    fn load_from_cache(_filename: &str) -> Rc<[u8]> {
        // dummy implementation
        Rc::new([0x68, 0x65, 0x6c, 0x6c, 0x6f])
    }

    fn load_object(filename: &str) -> Yoke<Cow<'static, [u8]>, Rc<[u8]>> {
        let rc: Rc<[u8]> = load_from_cache(filename);
        Yoke::<Cow<'static, [u8]>, Rc<[u8]>>::attach_to_cart(rc, deserialize);
        unimplemented!()
    }
    fn deserialize<'d>(data: &'d [u8]) -> <Cow<'static, [u8]> as Yokeable<'d>>::Output {
        bincode::deserialize_from(data).unwrap()
    }
}