[][src]Crate crndm

Corundum is a crate with an idiomatic persistent memory programming interface and leverages Rust’s type system to statically avoid most common persistent memory programming bugs. Corundum lets programmers develop persistent data structures using familiar Rust constructs and have confidence that they will be free of those bugs.

Statically Prevented Bugs

Common BugsExplanation Approach
Inter-Pool PointersA pointer in another pool which is unavailableType checking pools in persistent pointers.
P-to-V PointersA persistent pointer pointing at volatile memoryPersistent pointers accept only PSafe types and volatile pointers are !PSafe. Only, VCell allows single-execution P-to-V pointers.
V-to-P PointersA volatile pointer keeping a zero-referenced object aliveOnly VWeak allows V-to-P pointers which is a weak reference and does not keep data alive.
Unlogged UpdatesAn unrecoverable update to persistent dataModifications are enforced to be inside atomic transactions.
Data RaceUpdating persistent data simultaneously in two threadsMutable borrowing is limited to Mutex which uses a transaction-wide lock to provide both atomicity and isolation.
Locked MutexA persistent mutex remains locked on powerfailMutex uses VCell which resets at restart.
Memory Leaks*An allocated memory becomes unreachablePersistent objects, except the root object, cannot cross transaction boundaries, and memory allocation is available only inside a transaction. Therefore, the allocation can survive only if there is a reference from the root object (or a decedent of it) to the data.
* Cyclic references are not prevented in this version, which lead to a memory leak.

Persistent Objects

Persistent objects in Corundum are available through persistent pointers:

  • Pbox: A pointer type for persistent memory allocation.
  • Prc: A single-threaded reference-counting persistent pointer.
  • Parc: A thread-safe reference-counting persistent pointer.

Programming Model

Persistent memory is available as a file on a DAX-enable file system such as EXT4-DAX or NOVA. These files are called memory pools. Corundum allows memory pool types rather than memory pool objects to enforce pointer safety while compilation. The trait MemPool provides the necessary functionalities for the pool type.

The first step is to open a memory pool file in the program to be able to work with persistent data. The default module provides a default memory pool type (BuddyAlloc). To open a pool, we can invoke open<T>() function which [initializes and] returns a reference to the root object of type T.

Data modification is provided and allowed only through transactional interface. None of the persistent pointers is mutably dereferencing for safety. Mutable objects are allowed via interior mutability of any of the following memory cells:

  • LogCell<T,P> (or PCell<T>): An unborrowable, mutable persistent memory location for a value of type T in pool P.
  • LogRefCell<T,P> (or PRefCell<T>): A mutable persistent memory location with dynamically checked borrow rules for a value of type T in pool P.
  • Mutex<T,P> (or PMutex<T>): A mutual exclusion primitive useful for protecting shared persistent data of type T in pool P.

The following example creates a pool file for a linked-list-based stack, obtains a root object of type Node.

use crndm::default::*;
 
// Aliasing the pool type for convenience
type P = BuddyAlloc;
 
#[derive(Root)]
struct Node {
    value: i32,
    next: PRefCell<Option<Prc<Node>>>
}
 
fn main() {
    let head = P::open::<Node>("foo.pool", O_CF).unwrap();
 
    P::transaction(|j| {
        let mut h = head.next.borrow_mut(j);
        *h = Some(Prc::new(Node {
            value: rand::random(),
            next: head.next.pclone(j)
        }, j));
    }).expect("Unsuccessful transaction");
}

Re-exports

pub use stm::transaction;

Modules

alloc

Persistent Memory allocation APIs

boxed

A persistent pointer type for persistent memory allocation

cell

Persistent shareable mutable containers

clone

The PClone trait for types that cannot be 'implicitly copied'

convert
default

The default allocator module

ll

Low-level utils

prc

Single-threaded reference-counting persistent pointers

ptr

Manually manage memory through raw pointers

result

A Result type with string error messages

stm

Software transactional memory APIs

str

Persistent unicode string slices

sync

Useful synchronization primitives

vec

A contiguous growable array type with heap-allocated contents, written Vec

Macros

pool

This macro creates a new pool module and aliases for persistent types. It generates type BuddyAlloc which a persistent allocator type. It is recommended to alias the BuddyAlloc type for tidiness.

static_inner

This macro can be used to access static data of an arbitrary allocator

static_inner_object

This macro can be used to declare a static struct for the inner data of an arbitrary allocator.

Structs

AssertTxInSafe

A simple wrapper around a type to assert that it is safe to go in a transaction.

Traits

LooseTxInUnsafe

The implementing type can be asserted TxInSafe albeit being !TxInSafe by AssertTxInSafe.

PSafe

It marks the implementing type to be free of pointers to the volatile heap, and persistence safe.

RootObj

Creates a default value of the type

TxInSafe

It is equal to UnwindSafe, but is used to ensure doubly that mutable references cannot go inside a transaction.

TxOutSafe

It marks the implementing type to be safe crossing transaction boundaries

VSafe

Safe to be stored in volatile memory useful in VCell type to prevent storing persistent pointers in VCell

Derive Macros

PClone
Root