Struct wrc::WRC

pub struct WRC<T: ?Sized> { /* fields omitted */ }

WRC

A thread-safe weight reference counting smart-pointer for Rust.

Weighted Reference Counting

By using weights instead of direct reference counting WRC requires roughly half as many synchronisation operations and writes to the heap. Every time a WRC is cloned it's weight is split in two, with half allocated to the parent and half allocated to the child. When a WRC is dropped it's weight is removed from the total. When the total weight declines to zero then the referenced object is dropped.

The type WRC<T> provides shared ownership of type T, allocated on the heap. Invoking clone on WRC produces a new pointer to the shared value in the heap. When the last WRC pointer is dropped then the pointed-to value is also dropped.

See Wikipedia for more information about weighted reference counting.

Thread Safety

WRC<T> uses atomic operations for it's weight manipulations. This means that it is thread-safe. The disadvantage is that atomic operations are more expensive than ordinary memory accesses. The use of the weighted reference counting algorithm drastically reduces the number of synchronisation operations required to keep track of references.

Cycles

Currently there is no support in WRC for weak pointers or any other cycle breaking. If your usage causes you to create cycles of references you may want to investigate an alternative solution or manually force destruction of those objects.

Cloning references

Creating a new reference from an existing reference counted pointer is done using the Clone trait, implemented for WRC<T>.

Deref behaviour

WRC<T> automatically dereferences to T (via the Deref trait), so you can call T's methods on a value of type WTC<T>.

Examples

Sharing some immutable data between threads:

use wrc::WRC;
use std::thread;

let five = WRC::new(5);

for _ in 0..10 {
    let five = five.clone();

    thread::spawn(move || {
        println!("{:?}", five);
    });
}

Sharing a mutable AtomicUsize:

use wrc::WRC;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::thread;

let val = WRC::new(AtomicUsize::new(5));

for _ in 0..10 {
    let val = val.clone();

    thread::spawn(move || {
        let v = val.fetch_add(1, Ordering::SeqCst);
        println!("{:?}", v);
    });
}

See the rc documentation for more examples of reference counting in general.

Methods

impl<T> WRC<T>

pub fn new(data: T) -> WRC<T>

Construct a new WRC<T>.

Examples

use wrc::WRC;
let five = WRC::new(5);

pub fn total_weight(wrc: &WRC<T>) -> usize

Return the total weight of all references. Only used for testing. You're unlikely to need it.

pub fn clone(wrc: &WRC<T>) -> WRC<T>

Makes a clone of the WRC pointer.

This creates another pointer with the same ptr value, dividing the weight evenly between the new reference and the old reference.

Examples

use wrc::WRC;

let five = WRC::new(5);
WRC::clone(&five);

Trait Implementations

impl<T> Clone for WRC<T>

fn clone(&self) -> Self

Makes a clone of the WRC pointer.

This creates another pointer with the same ptr value, dividing the weight evenly between the new reference and the old reference.

Examples

use wrc::WRC;

let five = WRC::new(5);
five.clone();

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

Performs copy-assignment from source.

impl<T: Ord> Ord for WRC<T>

fn cmp(&self, other: &WRC<T>) -> Ordering

Comparison for two WRC's

The two are compared by calling cmp() on their ptr values.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

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

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<T: ?Sized + Sync + Send> Send for WRC<T>

impl<T: Eq> Eq for WRC<T>

impl<T: ?Sized> Drop for WRC<T>

fn drop(&mut self)

Drops the WRC.

This will decrement the total weight of the referenced object by the weight of this reference.

Examples

use wrc::WRC;

struct Foo;

impl Drop for Foo {
    fn drop(&mut self) {
        println!("dropped!");
    }
}

let foo = WRC::new(Foo);
let foo2 = foo.clone();

drop(foo);  // Doesn't print anything
drop(foo2); // Prints "dropped!"

impl<T: PartialOrd> PartialOrd<WRC<T>> for WRC<T>

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

Partial comparison for two WRC's

The two are compared by calling partial_cmp() on their ptr values.

fn lt(&self, other: &WRC<T>) -> bool

Less-than comparison for two WRC's

The two are compared by calling < on their ptr values.

fn le(&self, other: &WRC<T>) -> bool

Less-than or equal to comparison for two WRC's

The two are compared by calling <= on their ptr values.

fn gt(&self, other: &WRC<T>) -> bool

Greater-than comparison for two WRC's

The two are compared by calling > on their ptr values.

fn ge(&self, other: &WRC<T>) -> bool

Greater-than or equal comparison for two WRC's

The two are compared by calling >= on their ptr values.

impl<T: PartialEq> PartialEq<WRC<T>> for WRC<T>

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

Equality for WRC<T>

Two WRC's are equal if their ptr values are equal.

#[must_use]

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

This method tests for !=.

impl<T: Default> Default for WRC<T>

fn default() -> WRC<T>

Creates a new WRC<T> with the Default value of T.

impl<T: ?Sized + Sync + Send> Sync for WRC<T>

impl<T: Display> Display for WRC<T>

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

Formats the value using the given formatter

impl<T: Debug> Debug for WRC<T>

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

Formats the value using the given formatter.

impl<T> Deref for WRC<T>

type Target = Inner<T>

The resulting type after dereferencing

fn deref(&self) -> &Self::Target

The method called to dereference a value

impl<T: Hash> Hash for WRC<T>

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

Feeds this value into the given [Hasher].

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

Feeds a slice of this type into the given [Hasher].