Struct cfx_storage::CowNodeRef

pub struct CowNodeRef {
    pub node_ref: NodeRefDeltaMpt,
    /* private fields */
}

CowNodeRef facilities access and modification to trie nodes in multi-version MPT. It offers read-only access to the original trie node, and creates an unique owned trie node once there is any modification. The ownership is maintained centralized in owned_node_set which is passed into many methods as argument. When CowNodeRef is created from an owned node, the ownership is transferred into the CowNodeRef object. The visitor of MPT makes sure that ownership of any trie node is not transferred more than once at the same time.

Fields

node_ref: NodeRefDeltaMpt

Implementations

impl CowNodeRef

pub fn new_uninitialized_node<'a>( allocator: &'a RwLockReadGuard<'a, Slab<UnsafeCell<MemOptimizedTrieNode<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData>>, UnsafeCell<MemOptimizedTrieNode<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData>>>>, owned_node_set: &mut OwnedNodeSet, mpt_id: u16 ) -> Result<(Self, VacantEntry<'a, TrieNodeDeltaMptCell, TrieNodeDeltaMptCell>)>

pub fn new( node_ref: NodeRefDeltaMpt, owned_node_set: &OwnedNodeSet, mpt_id: u16 ) -> Self

pub fn take(&mut self) -> Self

Take the value out of Self. Self is safe to drop.

impl CowNodeRef

pub fn is_owned(&self) -> bool

pub fn get_trie_node<'a, 'c: 'a>( &'a mut self, node_memory_manager: &'c NodeMemoryManager<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData, LRU<u32, (u16, u32)>>, allocator: &'a RwLockReadGuard<'a, Slab<UnsafeCell<MemOptimizedTrieNode<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData>>, UnsafeCell<MemOptimizedTrieNode<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData>>>>, db: &mut DeltaDbOwnedReadTraitObj<'_> ) -> Result<GuardedValue<Option<MutexGuard<'c, CacheManagerDeltaMpts<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData, LRU<u32, (u16, u32)>>>>, MaybeOwnedTrieNode<'a>>>

The returned MaybeOwnedTrieNode is considered a borrow of CowNodeRef because when it’s owned user may use it as mutable borrow of TrieNode. The lifetime is bounded by allocator for slab and by node_memory_manager for cache.

Lifetime of cache is separated because holding the lock itself shouldn’t prevent any further calls on self.

pub fn delete_node( self, node_memory_manager: &NodeMemoryManager<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData, LRU<u32, (u16, u32)>>, owned_node_set: &mut OwnedNodeSet )

The trie node obtained from CowNodeRef is invalidated at the same time of delete_node and into_child. A trie node obtained from CowNodeRef will be inaccessible because it’s obtained through Self::get_trie_node, which has shorter lifetime because it’s a borrow of the CowNodeRef.

pub fn into_child(self) -> Option<NodeRefDeltaMptCompact>

pub fn delete_subtree( self, trie: &DeltaMpt, owned_node_set: &OwnedNodeSet, guarded_trie_node: GuardedValue<Option<MutexGuard<'_, CacheManagerDeltaMpts<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData, LRU<u32, (u16, u32)>>>>, MaybeOwnedTrieNodeAsCowCallParam>, key_prefix: CompressedPathRaw, values: &mut Vec<MptKeyValue>, db: &mut DeltaDbOwnedReadTraitObj<'_> ) -> Result<()>

The deletion is always successful. When return value is Error, the failing part is iteration.

pub fn get_or_compute_merkle( &mut self, trie: &DeltaMpt, owned_node_set: &mut OwnedNodeSet, allocator_ref: &'_ RwLockReadGuard<'_, Slab<UnsafeCell<MemOptimizedTrieNode<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData>>, UnsafeCell<MemOptimizedTrieNode<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData>>>>, db: &mut DeltaDbOwnedReadTraitObj<'_>, children_merkle_map: &mut BTreeMap<u32, VanillaChildrenTable<MerkleHash>>, parent_node_path_steps_plus_one: u16 ) -> Result<MerkleHash>

Get if unowned, compute if owned.

parent_node_path_steps_plus_one is the steps of path from root to the compressed_path. e.g. parent_node_path_steps_plus_one is 0 for root node, 1 for root node’s direct children.

pub fn iterate_internal<KVInserterType: KVInserter<MptKeyValue>>( &self, owned_node_set: &OwnedNodeSet, trie: &DeltaMpt, guarded_trie_node: GuardedValue<Option<MutexGuard<'_, CacheManagerDeltaMpts<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData, LRU<u32, (u16, u32)>>>>, MaybeOwnedTrieNodeAsCowCallParam>, key_prefix: CompressedPathRaw, values: &mut KVInserterType, db: &mut DeltaDbOwnedReadTraitObj<'_> ) -> Result<()>

pub fn commit_dirty_recursively<Transaction: BorrowMut<DeltaDbTransactionTraitObj>>( &mut self, trie: &DeltaMpt, owned_node_set: &mut OwnedNodeSet, trie_node: &mut TrieNodeDeltaMpt, commit_transaction: &mut AtomicCommitTransaction<'_, Transaction>, cache_manager: &mut CacheManagerDeltaMpts<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData, LRU<u32, (u16, u32)>>, allocator_ref: &'_ RwLockReadGuard<'_, Slab<UnsafeCell<MemOptimizedTrieNode<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData>>, UnsafeCell<MemOptimizedTrieNode<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData>>>>, children_merkle_map: &mut BTreeMap<u32, VanillaChildrenTable<MerkleHash>> ) -> Result<bool>

Recursively commit dirty nodes.

pub fn cow_merge_path( self, trie: &DeltaMpt, owned_node_set: &mut OwnedNodeSet, trie_node: GuardedValue<Option<MutexGuard<'_, CacheManagerDeltaMpts<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData, LRU<u32, (u16, u32)>>>>, MaybeOwnedTrieNodeAsCowCallParam>, child_node_ref: NodeRefDeltaMpt, child_index: u8, db: &mut DeltaDbOwnedReadTraitObj<'_> ) -> Result<CowNodeRef>

pub unsafe fn delete_value_unchecked_followed_by_node_deletion( &mut self, trie_node: GuardedValue<Option<MutexGuard<'_, CacheManagerDeltaMpts<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData, LRU<u32, (u16, u32)>>>>, MaybeOwnedTrieNodeAsCowCallParam> ) -> Box<[u8]>

When the node is unowned, it doesn’t make sense to do copy-on-write creation because the new node will be deleted immediately.

pub fn cow_set_compressed_path( &mut self, node_memory_manager: &NodeMemoryManager<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData, LRU<u32, (u16, u32)>>, owned_node_set: &mut OwnedNodeSet, path: CompressedPathRaw, trie_node: GuardedValue<Option<MutexGuard<'_, CacheManagerDeltaMpts<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData, LRU<u32, (u16, u32)>>>>, MaybeOwnedTrieNodeAsCowCallParam> ) -> Result<()>

pub unsafe fn cow_delete_value_unchecked( &mut self, node_memory_manager: &NodeMemoryManager<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData, LRU<u32, (u16, u32)>>, owned_node_set: &mut OwnedNodeSet, trie_node: GuardedValue<Option<MutexGuard<'_, CacheManagerDeltaMpts<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData, LRU<u32, (u16, u32)>>>>, MaybeOwnedTrieNodeAsCowCallParam> ) -> Result<Box<[u8]>>

pub fn cow_replace_value_valid( &mut self, node_memory_manager: &NodeMemoryManager<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData, LRU<u32, (u16, u32)>>, owned_node_set: &mut OwnedNodeSet, trie_node: GuardedValue<Option<MutexGuard<'_, CacheManagerDeltaMpts<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData, LRU<u32, (u16, u32)>>>>, MaybeOwnedTrieNodeAsCowCallParam>, value: Box<[u8]> ) -> Result<MptValue<Box<[u8]>>>

pub fn cow_modify_with_operation<'a, OutputType, FOwned: FnOnce(&'a mut TrieNodeDeltaMpt) -> OutputType, FRef: FnOnce(&'a TrieNodeDeltaMpt) -> (TrieNodeDeltaMpt, OutputType)>( &mut self, allocator: &'a RwLockReadGuard<'a, Slab<UnsafeCell<MemOptimizedTrieNode<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData>>, UnsafeCell<MemOptimizedTrieNode<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData>>>>, owned_node_set: &mut OwnedNodeSet, trie_node: GuardedValue<Option<MutexGuard<'_, CacheManagerDeltaMpts<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData, LRU<u32, (u16, u32)>>>>, MaybeOwnedTrieNodeAsCowCallParam>, f_owned: FOwned, f_ref: FRef ) -> Result<OutputType>

If owned, run f_owned on trie node; otherwise run f_ref on the read-only trie node to create the equivalent trie node and return value as the final state of f_owned.

pub fn cow_modify<'a>( &mut self, allocator: &'a RwLockReadGuard<'a, Slab<UnsafeCell<MemOptimizedTrieNode<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData>>, UnsafeCell<MemOptimizedTrieNode<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData>>>>, owned_node_set: &mut OwnedNodeSet, trie_node: GuardedValue<Option<MutexGuard<'_, CacheManagerDeltaMpts<<LRU<u32, (u16, u32)> as CacheAlgorithm>::CacheAlgoData, LRU<u32, (u16, u32)>>>>, MaybeOwnedTrieNodeAsCowCallParam> ) -> Result<&'a mut TrieNodeDeltaMpt>

Trait Implementations

impl Drop for CowNodeRef

fn drop(&mut self)

Assert that the CowNodeRef doesn’t own something.