Struct Holder

pub struct Holder<'k, T>
where
    T: Opaque + 'k,
{ /* private fields */ }

Holds an “opaqueified” T::Kind.

Note the lifetime, 'k. This can be anything, as long as T outlives it.

Examples

use core::cell::Cell;
 
use selfref::Holder;
use selfref::opaque;

#[derive(Default)]
struct Foo<'a> {
    foo: Cell<Option<&'a Foo<'a>>>,
}

struct FooKey;
opaque! {
    impl Opaque for FooKey {
        type Kind<'a> = Foo<'a>;
    }
}

fn main() {
    // We can use a closure here, but we need to give the compiler a hint.
    let holder = Holder::<'_, FooKey>::new_with(
        |foo| foo.build(Foo::default())
    );
}

Implementations

impl<'k, T> Holder<'k, T>

where T: Opaque,

pub fn new_with<F>(f: F) -> Self

where F: for<'a> FnOnce(&mut Builder<'a, T>), T::Kind<'k>: Sized,

Creates a new holder.

Examples

Simple example:

use core::cell::Cell;
 
use selfref::Holder;
use selfref::opaque;

#[derive(Default)]
struct Foo<'a> {
    foo: Cell<Option<&'a Foo<'a>>>,
}

struct FooKey;
opaque! {
    impl Opaque for FooKey {
        type Kind<'a> = Foo<'a>;
    }
}

fn main() {
    // We can use a closure here, but we need to help the compiler.
    let holder = Holder::<'_, FooKey>::new_with(
        |foo| foo.build(Foo::default())
    );
}

Lifetime parameters:

use core::cell::Cell;
use core::marker::PhantomData;
 
use selfref::Holder;
use selfref::opaque;

struct Foo<'a, 'b: 'a> {
    foo: Cell<Option<&'a Foo<'a, 'b>>>,
    t: &'b str,
}

struct FooKey<'b>(PhantomData<&'b str>);
opaque! {
    impl['b] Opaque for FooKey<'b> {
        type Kind<'a> = Foo<'a, 'b>;
    }
}

fn main() {
    let stack_array: [u8; 5] = *b"hello";
    // a non-'static &str
    let stack_str = core::str::from_utf8(&stack_array).unwrap();
    let holder = Holder::<'_, FooKey<'_>>::new_with(|foo| {
        foo.build(Foo {
            foo: Default::default(),
            t: stack_str,
        });
    });
}

impl<'k, T> Holder<'k, T>

where T: Opaque,

pub fn operate_in<'i, F, R>(self: Pin<&'i Self>, f: F) -> R

where F: for<'x> FnOnce(OperateIn<'x, T>) -> R,

Operates in this (pinned) holder.

This “unwraps” the value in this holder, and binds its lifetime to a new stack frame.

Examples

Simple example:

use core::cell::Cell;
 
use selfref::Holder;
use selfref::opaque;

#[derive(Default)]
struct Foo<'a> {
    foo: Cell<Option<&'a Foo<'a>>>,
}

struct FooKey;
opaque! {
    impl Opaque for FooKey {
        type Kind<'a> = Foo<'a>;
    }
}

fn main() {
    let holder = Box::pin(Holder::<'_, FooKey>::new_with(
        |foo| foo.build(Foo::default())
    ));
    // Actually making our Foo refer to itself.
    holder.as_ref().operate_in(
        |foo| {
            foo.foo.set(Some(foo.get_ref()));
        }
    );
}

With lifetime parameters:

use core::cell::Cell;
use core::marker::PhantomData;
use core::pin::Pin;
 
use selfref::Holder;
use selfref::opaque;

struct Foo<'a, 'b: 'a> {
    foo: Cell<Option<&'a Foo<'a, 'b>>>,
    t: &'b str,
}

struct FooKey<'b>(PhantomData<&'b str>);
opaque! {
    impl['b] Opaque for FooKey<'b> {
        type Kind<'a> = Foo<'a, 'b>;
    }
}

fn main() {
    let stack_array: [u8; 5] = *b"hello";
    // a non-'static &str
    let stack_str = core::str::from_utf8(&stack_array).unwrap();
    let holder = Box::pin(Holder::<'_, FooKey<'_>>::new_with(|foo| {
        foo.build(Foo {
            foo: Default::default(),
            t: stack_str,
        });
    }));
    // Actually making our Foo refer to itself.
    holder.as_ref().operate_in(|foo| {
        foo.foo.set(Some(foo.get_ref()));
    });
}