Struct Agc

pub struct Agc<T: Trace + 'static> { /* private fields */ }

Available on crate feature sync only.

A cycle-collected reference-counted smart pointer which may be shared across threads and supports concurrent collection.

Agc<T> provides shared ownership of a value of type T, allocated on the heap. Cloning it will produce a new Agc instance which points to the same allocation as the original Agc.

Unlike std::sync::Arc, Agc pointers may refer to each other in a way that creates cycles arbitrarily without causing leaks, provided that the program calls collect to collect those cycles.

• In most cases you must call collect to reclaim memory for dropped Agcs even if they are acyclical.
• You may call collect from any thread to collect cycles. The implementation of collect is intended to provide very low pause times for concurrently running threads, although it will block the thread which actually invokes collect until the collection is complete.
  • While the exact details are subject to change, the current implementation will block access to Agcs data for as long as it takes to update its metadata, and will only do so if that Agc is a candidate for collection.

Implementations

impl<T> Agc<T>

where T: Trace + 'static,

pub fn new(data: T) -> Self

Construct a new Agc containing data which will be automatically cleaned up with it is no longer reachable, even in the presence of cyclical references.

impl<T> Agc<T>

where T: Trace + 'static,

pub fn strong_count(this: &Self) -> usize

Retrieve the current number of strong references outstanding.

pub fn read(&self) -> Ref<'_, T>

Blocks the thread until it can acquire a non-exclusive reference into this Agc.

The returned object is an RAII guard which releases a shared lock. Multiple references may be taken out at the same time.

Deadlocks

May deadlock if the value is Dead. This should not occur under normal circumstances and likely indicates a bug in a Trace implementation.

Panics

Panics if the value is Dead. This should not occur under normal circumstances and likely indicates a bug in a Trace implementation.

pub fn try_borrow(&self) -> Option<Ref<'_, T>>

Try to get a non-exclusive reference into this Agc. This will not block the calling thread. This may fail if the object is being concurrently traced by the collector.

Returns None if the pointer is dead or exclusively referenced.

pub fn ptr_eq(this: &Self, other: &Self) -> bool

Returns true if both this & other point to the same allocation.

Trait Implementations

impl<T> Clone for Agc<T>

where T: Trace + 'static,

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Agc<T>

where T: Trace + 'static,

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

Formats the value using the given formatter.

impl<T> Drop for Agc<T>

where T: Trace + 'static,

fn drop(&mut self)

Executes the destructor for this type.

impl<T> Ord for Agc<T>

where T: Ord + Trace + 'static,

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 for Agc<T>

where T: PartialEq + Trace + 'static,

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

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

const 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 Agc<T>

where T: PartialOrd + Trace + 'static,

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 Agc<T>

where T: Trace + 'static,

fn visit_children(&self, visitor: &mut GcVisitor<'_>)

Visit the children of this type. The implementation should call visit_children on each owned value which implements Trace.

impl<T> Eq for Agc<T>

where T: Eq + Trace + 'static,