Struct Rc

pub struct Rc<'a, T> { /* private fields */ }

A single-threaded reference-counting pointer. ‘Rc’ stands for ‘Reference Counted’.

The inherent methods are all associated functions. This means you can not call them unexpectedly through deref-coercion the reference itself. Instead, you need to call them as Rc::try_unwrap(rc) etc. .

Compared to the standard library version, this will perform its own allocation. Instead, you can ask Bump to perform them or manually allocate guided by the necessary layout.

Implementations

impl<'a, T> Rc<'a, T>

pub fn new(val: T, memory: Uninit<'a, ()>) -> Self

Constructs a new Rc<T>.

See also Bump::rc, which encapsulates the process of allocation and construction in a single method call.

Panics

This function panics if the memory is not valid for the layout of Rc::layout.

Examples

use core::convert::TryInto;
use without_alloc::{alloc::LocalAllocLeakExt, rc::Rc};
use static_alloc::Bump;

struct Foo(u32);

let slab: Bump<[u8; 1024]> = Bump::uninit();
let layout = Rc::<Foo>::layout().try_into().unwrap();
let memory = slab.alloc_layout(layout).unwrap();
let rc = Rc::new(Foo(0), memory.uninit);

pub unsafe fn from_raw(init: Uninit<'a, T>) -> Self

Wrap a raw initialized value back into an Rc.

Safety

The block must originate from a previous call to [into_raw] and only the value must have been modified. The value must still be valid.

pub fn into_raw(rc: Self) -> Result<Uninit<'a, T>, Self>

Try to extract the memory.

This returns Some only when this is the last strong and weak reference to the value. The contained value will be preserved and is not dropped. Use from_raw to reinitialize a new Rc with the old value and memory.

Example

use without_alloc::{alloc::LocalAllocLeakExt, rc::Rc};
use static_alloc::Bump;

struct HotPotato;

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

let slab: Bump<[u8; 1024]> = Bump::uninit();
let foo = slab.rc(HotPotato).unwrap();

let raw = Rc::into_raw(foo).ok().unwrap();
// No panic. Value has not been dropped.

pub fn try_unwrap(rc: Self) -> Result<(T, Weak<'a, T>), Self>

Returns the contained value, if the Rc has exactly one strong reference.

Also returns the managed memory in the form of a Weak. This is unusual but the best choice for potentially recovering it. Returning the memory directly is not possible since other Weak<T> instances may still point to it. If you are not interested in the memory you can simply drop the Weak.

pub fn downgrade(rc: &Self) -> Weak<'a, T>

Create a new Weak pointer to the value.

The weak pointer shares ownership over the memory but not over the value itself.

Example

use without_alloc::{alloc::LocalAllocLeakExt, rc::Rc};
use static_alloc::Bump;

struct Foo;

let slab: Bump<[u8; 1024]> = Bump::uninit();
let foo = slab.rc(Foo).unwrap();
let weak = Rc::downgrade(&foo);

assert_eq!(Rc::weak_count(&foo), 2);
drop(foo);

assert_eq!(weak.weak_count(), 1);

impl<T> Rc<'_, T>

pub fn layout() -> Layout

Get the layout for memory passed to Rc::new.

You should not rely on the value returned here. The two guarantees are: the size of the layout is at least as large as the input type and it is never empty.

An Rc does not simply point to a lone instance of a type but instead adds some small metadata (two pointer-sized counters). To keep the implementation details private, this method allows allocation of properly sized regions without exposing the exact type that will be stored on the heap.

Examples

use without_alloc::rc::Rc;

struct Foo(u32);
struct Empty;

assert!(Rc::<Foo>::layout().size() >= 4);
assert!(Rc::<Empty>::layout().size() > 0);

pub fn weak_count(rc: &Self) -> usize

Gets the number of weak pointers to the value.

Note that all Rc to the same value count as one weak pointer in total.

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

Gets the number of strong pointers to the value.

pub fn get_mut(rc: &mut Self) -> Option<&mut T>

Try to retrieve a mutable reference to the value.

This method will only succeed if there are no other pointers to the same value, neither strong ones nor weak ones.

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

Check if two Rcs point to the same data.

This will never compare the values but simply inspect the inner pointers.

Example

use without_alloc::{alloc::LocalAllocLeakExt, rc::Rc};
use static_alloc::Bump;

struct Foo;

let slab: Bump<[u8; 1024]> = Bump::uninit();

// Two Rc's pointing to the same data.
let foo = slab.rc(Foo).unwrap();
let foo2 = Rc::clone(&foo);

// An unrelated allocation.
let not_foo = slab.rc(Foo).unwrap();

assert!( Rc::ptr_eq(&foo, &foo2));
assert!(!Rc::ptr_eq(&foo, &not_foo));

Trait Implementations

impl<T> AsRef<T> for Rc<'_, T>

fn as_ref(&self) -> &T

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

impl<T> Borrow<T> for Rc<'_, T>

fn borrow(&self) -> &T

Immutably borrows from an owned value.

impl<T> Clone for Rc<'_, T>

fn clone(&self) -> Self

Clone the Rc.

This will increment the strong reference count. Only an Rc pointing to a unique value can unwrap or point to the value mutably.

Examples

use without_alloc::{alloc::LocalAllocLeakExt, rc::Rc};
use static_alloc::Bump; 

struct Foo;

let slab: Bump<[u8; 1024]> = Bump::uninit();

let mut foo  = slab.rc(Foo).unwrap();
assert!(Rc::get_mut(&mut foo).is_some());

let foo2 = Rc::clone(&foo);
assert!(Rc::get_mut(&mut foo).is_none());

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

Performs copy-assignment from source.

impl<T: Debug> Debug for Rc<'_, T>

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

Formats the value using the given formatter.

impl<T> Deref for Rc<'_, T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T: Display> Display for Rc<'_, T>

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

Formats the value using the given formatter.

impl<T> Drop for Rc<'_, T>

fn drop(&mut self)

Drops the Rc.

This will decrement the strong reference count. If the strong reference count reaches zero then the only other references (if any) are Weak, so we drop the inner value.

Examples

use without_alloc::{alloc::LocalAllocLeakExt, rc::Rc};
use static_alloc::Bump;

struct Foo;

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

let slab: Bump<[u8; 1024]> = Bump::uninit();

let foo  = slab.rc(Foo).unwrap();
let foo2 = Rc::clone(&foo);

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

impl<T: Hash> Hash for Rc<'_, 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> Ord for Rc<'_, T>

fn cmp(&self, other: &Rc<'_, T>) -> 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<'a, 'b, T: PartialEq> PartialEq<Rc<'b, T>> for Rc<'a, T>

fn eq(&self, other: &Rc<'_, T>) -> bool

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

fn ne(&self, other: &Rc<'_, T>) -> bool

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

impl<'a, 'b, T: PartialOrd> PartialOrd<Rc<'b, T>> for Rc<'a, T>

fn partial_cmp(&self, other: &Rc<'_, T>) -> Option<Ordering>

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

fn lt(&self, other: &Rc<'_, T>) -> bool

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

fn le(&self, other: &Rc<'_, T>) -> bool

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

fn ge(&self, other: &Rc<'_, T>) -> bool

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

fn gt(&self, other: &Rc<'_, T>) -> bool

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

impl<T> Pointer for Rc<'_, T>

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

Formats the value using the given formatter.

impl<T: Eq> Eq for Rc<'_, T>