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

pub const fn as_any(self) -> AnyRef

Returns this reference as an untyped reference.

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.

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 duplicate 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,

Restrict a value to a certain interval.

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

where T: Collectable,

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

Tests for self and other values to be equal, and is used by ==.

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

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

Tests for self and other values to be equal, and is used by ==.

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

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

Tests for self and other values to be equal, and is used by ==.

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

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

Tests for self and other values to be equal, and is used by ==.

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

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

Tests for self and other values to be equal, and is used by ==.

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

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

Tests for self and other values to be equal, and is used by ==.

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

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

Tests for self and other values to be equal, and is used by ==.

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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,