Trait Yokeable

unsafe trait Yokeable<'a>: 'static

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)] 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)] custom derive instead. We include an example in case you have your own zero-copy abstractions you wish to make yokeable.

# 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)) }
    }
}

Associated Types

type Output: Outlives("'a")

This type MUST be Self with the 'static replaced with 'a, i.e. Self<'a>

Required Methods

fn transform(self: &'a Self) -> &'a <Self as >::Output

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_owned(self: Self) -> <Self as >::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.

unsafe fn make(from: <Self as >::Output) -> Self

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>

fn transform_mut<F>(self: &'a mut Self, f: F)
where
    F: 'static + for<'b> FnOnce(&'b mut <Self as >::Output)

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>

# 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:

# 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:

# 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.

Implementors