[−][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 Bugs | Explanation | Approach |
---|---|---|
Inter-Pool Pointers | A pointer in another pool which is unavailable | Type checking pools in persistent pointers. |
P-to-V Pointers | A persistent pointer pointing at volatile memory | Persistent pointers accept only PSafe types and volatile pointers are !PSafe . Only, VCell allows single-execution P-to-V pointers. |
V-to-P Pointers | A volatile pointer keeping a zero-referenced object alive | Only VWeak allows V-to-P pointers which is a weak reference and does not keep data alive. |
Unlogged Updates | An unrecoverable update to persistent data | Modifications are enforced to be inside atomic transaction s. |
Data Race | Updating persistent data simultaneously in two threads | Mutable borrowing is limited to Mutex which uses a transaction-wide lock to provide both atomicity and isolation. |
Locked Mutex | A persistent mutex remains locked on powerfail | Mutex uses VCell which resets at restart. |
Memory Leaks* | An allocated memory becomes unreachable | Persistent 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 transaction
al
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>
(orPCell<T>
): An unborrowable, mutable persistent memory location for a value of typeT
in poolP
.LogRefCell<T,P>
(orPRefCell<T>
): A mutable persistent memory location with dynamically checked borrow rules for a value of typeT
in poolP
.Mutex<T,P>
(orPMutex<T>
): A mutual exclusion primitive useful for protecting shared persistent data of typeT
in poolP
.
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 |
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 |
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 |
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 |
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 |
Derive Macros
PClone | |
Root |