Struct refuse::Ref

pub struct Ref<T> { /* private fields */ }

A reference to data stored in a garbage collector.

Unlike a Root<T>, this type is not guaranteed to have access to its underlying data. If no Collectable reachable via all active Roots marks this allocation, it will be collected.

Because of this, direct access to the data is not provided. To obtain a reference, call Ref::load().

Loading a reference

Ref::load() is used to provide a reference to data stored in the garbage collector.

use refuse::{CollectionGuard, Ref};

let guard = CollectionGuard::acquire();
let data = Ref::new(42, &guard);

assert_eq!(data.load(&guard), Some(&42));

References returned from Ref::load() are tied to the lifetime of the guard. This ensures that a reference to data can only be held between moments when the garbage collector can be run. For example these usages are prevented by the compiler:

let guard = CollectionGuard::acquire();
let data = Ref::new(42, &guard);
let reference = data.load(&guard).unwrap();

drop(guard);

// error[E0505]: cannot move out of `guard` because it is borrowed
assert_eq!(reference, &42);

let mut guard = CollectionGuard::acquire();
let data = Ref::new(42, &guard);
let reference = data.load(&guard).unwrap();

guard.yield_to_collector();

// error[E0502]: cannot borrow `guard` as mutable because it is also borrowed as immutable
assert_eq!(reference, &42);

Implementations

impl<T> Ref<T>

where T: Collectable,

pub fn new<'a>(value: T, guard: impl AsRef<CollectionGuard<'a>>) -> Self

Stores value in the garbage collector, returning a “weak” reference to it.

Examples found in repository

examples/map_as.rs (line 34)

fn main() {
    let guard = CollectionGuard::acquire();
    let gced: Ref<SomeType> = Ref::new(SomeType, &guard);
    let type_erased: AnyRef = gced.as_any();
    type_erased
        .load_mapped::<dyn SomeTrait>(&guard)
        .unwrap()
        .do_something();
}

examples/allocate_a_lot.rs (line 13)

fn main() {
    std::thread::scope(|s| {
        for _ in 0..16 {
            s.spawn(|| {
                let mut guard = CollectionGuard::acquire();
                for _ in 0..100 {
                    for _ in 0..100 {
                        Ref::new([0; 32], &guard);
                    }
                    guard.yield_to_collector();
                }
            });
        }
    });
}

examples/trace.rs (line 14)

fn main() {
    let mut guard = CollectionGuard::acquire();

    let message = Ref::new(String::from("Hello!"), &guard);
    let error = Root::new(Error { message }, &guard);

    // Because `error` is a Root and refers to the message,
    guard.collect();

    assert_eq!(message.load(&guard).expect("still alive"), "Hello!");

    // After we drop the Root, the message will be able to be collected.
    drop(error);
    guard.collect();
    assert_eq!(message.load(&guard), None);
}

examples/basic.rs (line 7)

fn main() {
    let guard = CollectionGuard::acquire();
    // Allocate a vec![Ref(1), Ref(2), Ref(3)].
    let values: Vec<Ref<u32>> = (1..=3).map(|value| Ref::new(value, &guard)).collect();
    let values = Root::new(values, &guard);
    drop(guard);

    // Manually execute the garbage collector. Our data will not be freed,
    // since `values` is a "root" reference.
    refuse::collect();

    // Root references allow direct access to their data, even when a
    // `CollectionGuard` isn't held.
    let (one, two, three) = (values[0], values[1], values[2]);

    // Accessing the data contained in a `Ref` requires a guard, however.
    let mut guard = CollectionGuard::acquire();
    assert_eq!(one.load(&guard), Some(&1));
    assert_eq!(two.load(&guard), Some(&2));
    assert_eq!(three.load(&guard), Some(&3));

    // Dropping our root will allow the collector to free our `Ref`s.
    drop(values);
    guard.collect();
    assert_eq!(one.load(&guard), None);
}

pub const fn as_any(self) -> AnyRef

Returns this reference as an untyped reference.

Examples found in repository

examples/map_as.rs (line 35)

fn main() {
    let guard = CollectionGuard::acquire();
    let gced: Ref<SomeType> = Ref::new(SomeType, &guard);
    let type_erased: AnyRef = gced.as_any();
    type_erased
        .load_mapped::<dyn SomeTrait>(&guard)
        .unwrap()
        .do_something();
}

pub fn load<'guard>( &self, guard: &'guard CollectionGuard<'_> ) -> Option<&'guard T>

Loads a reference to the underlying data. Returns None if the data has been collected and is no longer available.

Examples found in repository

examples/trace.rs (line 20)

fn main() {
    let mut guard = CollectionGuard::acquire();

    let message = Ref::new(String::from("Hello!"), &guard);
    let error = Root::new(Error { message }, &guard);

    // Because `error` is a Root and refers to the message,
    guard.collect();

    assert_eq!(message.load(&guard).expect("still alive"), "Hello!");

    // After we drop the Root, the message will be able to be collected.
    drop(error);
    guard.collect();
    assert_eq!(message.load(&guard), None);
}

examples/basic.rs (line 21)

fn main() {
    let guard = CollectionGuard::acquire();
    // Allocate a vec![Ref(1), Ref(2), Ref(3)].
    let values: Vec<Ref<u32>> = (1..=3).map(|value| Ref::new(value, &guard)).collect();
    let values = Root::new(values, &guard);
    drop(guard);

    // Manually execute the garbage collector. Our data will not be freed,
    // since `values` is a "root" reference.
    refuse::collect();

    // Root references allow direct access to their data, even when a
    // `CollectionGuard` isn't held.
    let (one, two, three) = (values[0], values[1], values[2]);

    // Accessing the data contained in a `Ref` requires a guard, however.
    let mut guard = CollectionGuard::acquire();
    assert_eq!(one.load(&guard), Some(&1));
    assert_eq!(two.load(&guard), Some(&2));
    assert_eq!(three.load(&guard), Some(&3));

    // Dropping our root will allow the collector to free our `Ref`s.
    drop(values);
    guard.collect();
    assert_eq!(one.load(&guard), None);
}

pub fn as_root(&self, guard: &CollectionGuard<'_>) -> Option<Root<T>>

Loads a root reference to the underlying data. Returns None if the data has been collected and is no longer available.

Trait Implementations

impl<T> AsRef<Ref<T>> for Ref<T>

fn as_ref(&self) -> &Ref<T>

Converts this type into a shared reference of the (usually inferred) input type.

impl<T> AsRef<Ref<T>> for Root<T>

where T: Collectable,

fn as_ref(&self) -> &Ref<T>

Converts this type into a shared reference of the (usually inferred) input type.

impl<T> Clone for Ref<T>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for Ref<T>

where T: Collectable + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> From<&Ref<T>> for AnyRef

where T: Collectable,

fn from(value: &Ref<T>) -> Self

Converts to this type from the input type.

impl<T> From<Ref<T>> for AnyRef

where T: Collectable,

fn from(value: Ref<T>) -> Self

Converts to this type from the input type.

impl<T> Hash for Ref<T>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T> Ord for Ref<T>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl<T> PartialEq<&AnyRef> for Ref<T>

where T: Collectable,

fn eq(&self, other: &&AnyRef) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialEq<&Ref<T>> for Root<T>

where T: Collectable,

fn eq(&self, other: &&Ref<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialEq<&Root<T>> for Ref<T>

where T: Collectable,

fn eq(&self, other: &&Root<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialEq<AnyRef> for Ref<T>

where T: Collectable,

fn eq(&self, other: &AnyRef) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialEq<Ref<T>> for Root<T>

where T: Collectable,

fn eq(&self, other: &Ref<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialEq<Root<T>> for Ref<T>

where T: Collectable,

fn eq(&self, other: &Root<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialEq for Ref<T>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialOrd for Ref<T>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T> Trace for Ref<T>

where T: Collectable,

const MAY_CONTAIN_REFERENCES: bool = true

If true, this type may contain references and should have its trace() function invoked during the collector’s “mark” phase.

fn trace(&self, tracer: &mut Tracer<'_>)

Traces all refrences that this value references.

impl<T> Copy for Ref<T>

impl<T> Eq for Ref<T>

impl<T> Send for Ref<T>

where T: Send,

impl<T> Sync for Ref<T>

where T: Sync,