Struct crndm::prc::Prc

pub struct Prc<T: PSafe + ?Sized, A: MemPool> { /* fields omitted */ }

A single-thread reference-counting persistent pointer. 'Prc' stands for 'Persistent Reference Counted'.

The main aspect of Prc<T> is that its counters are transactional which means that functions pclone, downgrade, and upgrade require a Journal to operate. In other words, you need to wrap them in a transaction.

Prc uses reference counting to manage memory. Although it provides a fast solution for deallocation without scan, cyclic references yield a memory leak. At this point, we have not provided a static solution to detect cyclic references. However, following Rust's partial solution for that, you may use Weak references for reference cycles.

References to data can be strong (using pclone), weak (using downgrade), or volatile weak (using volatile). The first two generate NV-to-NV pointers, while the last on is a V-to-NV pointer. Please see Weak and VWeak for more details on their implementation and safety.

Examples

use crndm::prc::Prc;
use crndm::clone::PClone;
 
P::transaction(|j| {
    let p = Prc::<i32,P>::new(1, j);
 
    // Create a new persistent strong reference
    let s = p.pclone(j);
 
    assert_eq!(*p, *s);
    assert_eq!(2, Prc::strong_count(&p));
    assert_eq!(0, Prc::weak_count(&p));
 
    // Create a new persistent weak reference
    let w = Prc::downgrade(&p, j);
    assert_eq!(2, Prc::strong_count(&p));
    assert_eq!(1, Prc::weak_count(&p));
 
    // Create a new volatile weak reference
    let v = Prc::volatile(&p);
    assert_eq!(2, Prc::strong_count(&p));
    assert_eq!(1, Prc::weak_count(&p));
 
    // Upgrade the persistent weak ref to a strong ref
    let ws = w.upgrade(j).unwrap();
    assert_eq!(3, Prc::strong_count(&p));
    assert_eq!(1, Prc::weak_count(&p));
 
    // Upgrade the volatile weak ref to a strong ref
    let vs = w.upgrade(j).unwrap();
    assert_eq!(4, Prc::strong_count(&p));
    assert_eq!(1, Prc::weak_count(&p));
}).unwrap();

Implementations

impl<T: PSafe, A: MemPool> Prc<T, A>

pub fn new(value: T, journal: &Journal<A>) -> Prc<T, A>

Constructs a new Prc<T>.

It also creates a DropOnFailure log to make sure that if the program crashes, the allocation drops of recovery.

Examples

use crndm::prc::Prc;

P::transaction(|j| {
    let five = Prc::new(5, j);
}).unwrap();

pub fn new_uninit(journal: &Journal<A>) -> Prc<MaybeUninit<T>, A>

Constructs a new Prc with uninitialized contents.

A DropOnFailure log is taken for the allocation.

Examples

use crndm::prc::Prc;

P::transaction(|j| {
    let mut five = Prc::<u32,Heap>::new_uninit(j);

    let five = unsafe {
        // Deferred initialization:
        Prc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);

        five.assume_init()
    };

    assert_eq!(*five, 5)
}).unwrap();

pub fn new_zeroed(journal: &Journal<A>) -> Prc<MaybeUninit<T>, A>

Constructs a new Prc with uninitialized contents, with the memory being filled with 0 bytes.

See MaybeUninit::zeroed for examples of correct and incorrect usage of this method.

Examples

use crndm::prc::Prc;

P::transaction(|j| {
    let zero = Prc::<i32,P>::new_zeroed(j);
    let zero = unsafe { zero.assume_init() };

    assert_eq!(*zero, 0)
}).unwrap();

pub fn from(p: Prc<T, A>) -> Self

Owns contents of p without cloning, leaving p untouched

impl<T: PSafe, A: MemPool> Prc<MaybeUninit<T>, A>

pub unsafe fn assume_init(self) -> Prc<T, A>

Converts to Rc<T>.

Safety

As with MaybeUninit::assume_init, it is up to the caller to guarantee that the inner value really is in an initialized state. Calling this when the content is not yet fully initialized causes immediate undefined behavior.

Examples

use crndm::prc::Prc;

crndm::transaction(|j| {
    let mut five = Prc::<u32,P>::new_uninit(j);

    let five = unsafe {
        // Deferred initialization:
        Prc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);

        five.assume_init()
    };

    assert_eq!(*five, 5);
}).unwrap();

impl<T: PSafe, A: MemPool> Prc<MaybeUninit<T>, A>

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

Returns a mutable reference into the given Prc, if there are no other Prc or Weak pointers to the same allocation.

Returns None otherwise, because it is not safe to mutate a shared value. It only works for Prc<MaybeUninit<T>> to be able to defer the initialization.

Examples

use crndm::prc::Prc;

P::transaction(|j| {
    let mut five = Prc::<u32,P>::new_uninit(j);

    let five = unsafe {
        // Deferred initialization:
        Prc::get_mut(&mut five).unwrap().as_mut_ptr().write(5);

        five.assume_init()
    };

    assert_eq!(*five, 5)
}).unwrap();

pub unsafe fn get_mut_unchecked(this: &mut Self) -> &mut MaybeUninit<T>

Returns a mutable reference into the given Prc, without any check.

It only works for Prc<MaybeUninit<T>> to be able to defer the initialization.

Safety

Any other Prc or Weak pointers to the same allocation must not be dereferenced for the duration of the returned borrow. This is trivially the case if no such pointers exist, for example immediately after Rc::new.

Examples

use crndm::prc::Prc;

P::transaction(|j| {
    let mut five = Prc::<i32,P>::new_uninit(j);

    let five = unsafe {
        // Deferred initialization:
        Prc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);

        five.assume_init()
    };

    assert_eq!(*five, 5);
}).unwrap();

impl<T: PSafe + ?Sized, A: MemPool> Prc<T, A>

pub fn downgrade(this: &Self, journal: &Journal<A>) -> Weak<T, A>

Creates a new Weak pointer to this allocation.

Examples

use crndm::prc::Prc;

P::transaction(|j| {
    let five = Prc::new(5, j);
    let _weak_five = Prc::downgrade(&five, j);
}).unwrap()

pub fn volatile(this: &Self) -> VWeak<T, A>

Creates a new VWeak pointer to this allocation.

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

Gets the number of Weak pointers to this allocation.

Examples

use crndm::prc::Prc;

P::transaction(|j| {
    let five = Prc::new(5, j);

    let _weak_five = Prc::downgrade(&five, j);
    assert_eq!(1, Prc::weak_count(&five));
}).unwrap()

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

Gets the number of Weak pointers to this allocation.

Examples

use crndm::prc::Prc;
use crndm::clone::PClone;

P::transaction(|j| {
    let five = Prc::new(5, j);
    let _also_five = Prc::pclone(&five, j);
    assert_eq!(2, Prc::strong_count(&five));
}).unwrap();

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

Returns true if the two Prcs point to the same allocation (in a vein similar to ptr::eq).

Examples

use crndm::prc::Prc;
use crndm::clone::PClone;

P::transaction(|j| {
    let five = Prc::new(5, j);
    let same_five = Prc::pclone(&five, j);
    let other_five = Prc::new(5, j);

    assert!(Prc::ptr_eq(&five, &same_five));
    assert!(!Prc::ptr_eq(&five, &other_five));
}).unwrap();

Trait Implementations

impl<T: PSafe + ?Sized, A: MemPool> AsRef<T> for Prc<T, A>

pub fn as_ref(&self) -> &T

Performs the conversion.

impl<T: PSafe + ?Sized, A: MemPool> Borrow<T> for Prc<T, A>

pub fn borrow(&self) -> &T

Immutably borrows from an owned value.

impl<T: Debug + PSafe + ?Sized, A: MemPool> Debug for Prc<T, A>

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

Formats the value using the given formatter.

impl<T: PSafe + ?Sized, A: MemPool> Deref for Prc<T, A>

type Target = T

The resulting type after dereferencing.

pub fn deref(&self) -> &T

Dereferences the value.

impl<T: Display + PSafe + ?Sized, A: MemPool> Display for Prc<T, A>

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

Formats the value using the given formatter.

impl<T: PSafe + ?Sized, A: MemPool> Drop for Prc<T, A>

pub fn drop(&mut self)

Drops the Prc safely

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 on commit using a DropOnCommit log.

Examples

use crndm::prc::Prc;
use crndm::clone::PClone;

struct Foo;

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

P::transaction(|j| {
    let foo  = Prc::new(Foo, j);
    let foo2 = Prc::pclone(&foo, j);

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

impl<T: Eq + PSafe + ?Sized, A: MemPool> Eq for Prc<T, A>

impl<T: Hash + PSafe + ?Sized, A: MemPool> Hash for Prc<T, A>

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

Feeds this value into the given Hasher.

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

Feeds a slice of this type into the given Hasher.

impl<T: Ord + PSafe + ?Sized, A: MemPool> Ord for Prc<T, A>

pub fn cmp(&self, other: &Prc<T, A>) -> Ordering

This method returns an Ordering between self and other.

#[must_use]pub fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]pub fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]pub fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<T: PSafe + ?Sized, A: MemPool> PClone<A> for Prc<T, A>

pub fn pclone(&self, journal: &Journal<A>) -> Prc<T, A>

Creates a new strong reference to the object

It increments the strong reference counter in a failure-atomic manner. When a transaction is aborted or power fails, every strong references to the object should be gone, and the counters should rollback to the consistent state before the transaction.

Examples

let root = P::open::<Prc<i32>>("foo.pool", O_CF).unwrap();
 
let _ = P::transaction(|j| {
    let _n1 = root.pclone(j);
    let _n2 = root.pclone(j);
    let _n3 = root.pclone(j);
    assert_eq!(4, Prc::strong_count(&root));
    panic!("abort")
});
 
assert_eq!(1, Prc::strong_count(&root));

pub fn pclone_from(&mut self, source: &Self, journal: &Journal<A>)

Performs copy-assignment from source.

impl<T: PartialEq + PSafe + ?Sized, A: MemPool> PartialEq<Prc<T, A>> for Prc<T, A>

pub fn eq(&self, other: &Prc<T, A>) -> bool

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

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T: PartialOrd + PSafe + ?Sized, A: MemPool> PartialOrd<Prc<T, A>> for Prc<T, A>

pub fn partial_cmp(&self, other: &Prc<T, A>) -> Option<Ordering>

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

pub fn lt(&self, other: &Prc<T, A>) -> bool

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

pub fn le(&self, other: &Prc<T, A>) -> bool

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

pub fn gt(&self, other: &Prc<T, A>) -> bool

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

pub fn ge(&self, other: &Prc<T, A>) -> bool

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

impl<T: PSafe, A: MemPool> PmemUsage for Prc<T, A>

pub default fn size_of() -> usize

Size of the object on Persistent Memory Assuming that self is not on PM, or considered else were, the size of allocated persistent memory is the sum of all persistent objects pointed by this object.

pub fn size_of_pmem() -> usize

Size of the object on Persistent Memory including Self Assuming that self is also on PM (e.g. the root object), the size of allocated persistent memory includes the size of all objects pointed by this object and the size Self.

impl<T: PSafe + PmemUsage + ?Sized, A: MemPool> PmemUsage for Prc<T, A>

pub fn size_of() -> usize

Size of the object on Persistent Memory Assuming that self is not on PM, or considered else were, the size of allocated persistent memory is the sum of all persistent objects pointed by this object.

pub fn size_of_pmem() -> usize

Size of the object on Persistent Memory including Self Assuming that self is also on PM (e.g. the root object), the size of allocated persistent memory includes the size of all objects pointed by this object and the size Self.

impl<T: PSafe + ?Sized, A: MemPool> Pointer for Prc<T, A>

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

Formats the value using the given formatter.

impl<T: RootObj<A> + PSafe, A: MemPool> RootObj<A> for Prc<T, A>

pub default fn init(journal: &Journal<A>) -> Prc<T, A>

impl<T: Default + PSafe + ?Sized, A: MemPool> RootObj<A> for Prc<T, A>

pub default fn init(journal: &Journal<A>) -> Prc<T, A>

impl<T: ?Sized, A: MemPool> !Send for Prc<T, A>

impl<T: ?Sized, A: MemPool> !Sync for Prc<T, A>

impl<T: ?Sized, A: MemPool> !TxOutSafe for Prc<T, A>

impl<T: PSafe + ?Sized, A: MemPool> Unpin for Prc<T, A>

impl<T: ?Sized, A: MemPool> !VSafe for Prc<T, A>