Refined the implementation of XArray and added copy-on-write cloning.

src/cow.rs

@@ -0,0 +1,44 @@
+use crate::*;
+
+/// Provide a method for XArray and XNode to check whether copy-on-write is necessary and perform it.
+pub trait CowCheck<I: ItemEntry> {
+    /// By examining the target entry that is about to be operated on,
+    /// perform copy-on-write when the target entry is subject to a mutable operation and is shared with other XArrays.
+    fn copy_on_write<'a>(&'a mut self, entry: &'a XEntry<I>, offset: u8) -> &'a XEntry<I>;
+}
+
+impl<I: ItemEntry> CowCheck<I> for XNodeInner<I> {
+    default fn copy_on_write<'a>(&'a mut self, entry: &'a XEntry<I>, _offset: u8) -> &'a XEntry<I> {
+        entry
+    }
+}
+
+impl<I: ItemEntry + Clone> CowCheck<I> for XNodeInner<I> {
+    fn copy_on_write<'a>(&'a mut self, entry: &'a XEntry<I>, offset: u8) -> &'a XEntry<I> {
+        if entry.is_node() && entry.node_strong_count().unwrap() > 1 {
+            let new_entry = deep_clone_node_entry(entry);
+            let _ = self.set_entry(offset, new_entry);
+            self.entry(offset)
+        } else {
+            entry
+        }
+    }
+}
+
+impl<I: ItemEntry> CowCheck<I> for XArray<I> {
+    default fn copy_on_write<'a>(&'a mut self, entry: &'a XEntry<I>, _offset: u8) -> &'a XEntry<I> {
+        entry
+    }
+}
+
+impl<I: ItemEntry + Clone> CowCheck<I> for XArray<I> {
+    fn copy_on_write<'a>(&'a mut self, entry: &'a XEntry<I>, _offset: u8) -> &'a XEntry<I> {
+        if entry.is_node() && entry.node_strong_count().unwrap() > 1 {
+            let new_entry = deep_clone_node_entry(entry);
+            let _ = self.set_head(new_entry);
+            self.head()
+        } else {
+            entry
+        }
+    }
+}

src/cursor.rs

@@ -0,0 +1,283 @@
+use std::marker::PhantomData;
+
+use crate::*;
+
+/// A `Cursor` can traverse in the `XArray` and have a target operated `XEntry`, which is stored in the `index` of `XArray`.
+/// `Cursor` can be only created by an `XArray`, and will hold its immutable reference, and can only perform read-only operations
+/// for the corresponding `XArray`.
+/// When a cursor traverses an XArray, at any given moment, it is positioned on an XNode. If not, it means that
+/// the cursor has not begin to traverse. Its member `offset` indicates the next XEntry it will move to, which is the `slots[offset]` inside the current XNode.
+///
+/// At the same time, multiple Cursors are allowed to operate on a single XArray.
+pub(crate) struct Cursor<'a, I>
+where
+    I: ItemEntry,
+{
+    /// The `XArray` the cursor located in.
+    xa: &'a XArray<I>,
+    /// The target index of the cursor in the belonged `XArray`.
+    index: u64,
+    /// The next XEntry to be operated on is at 'offset' in the slots of the current XNode.
+    offset: u8,
+    /// Current positioned XNode.
+    current_node: Option<&'a XNode<I, ReadOnly>>,
+    _marker: PhantomData<I>,
+}
+
+impl<'a, I: ItemEntry> Cursor<'a, I> {
+    /// Create an `Cursor` to perform read related operations on the `XArray`.
+    pub(crate) fn new(xa: &'a XArray<I>, index: u64) -> Self {
+        Self {
+            xa,
+            index,
+            offset: 0,
+            current_node: None,
+            _marker: PhantomData,
+        }
+    }
+
+    /// Move the `Cursor` to the `XNode` that `node_entry` points to, and update the cursor's state based on its target index.
+    /// Return a reference to the `XEntry` within the slots of the current XNode that needs to be operated on.
+    fn move_to(&mut self, node_entry: &'a XEntry<I>) -> Option<RefEntry<'a, I>> {
+        if let Some(node) = node_entry.as_node() {
+            let (current_entry, offset) = {
+                let offset = node.entry_offset(self.index);
+                let current_entry = node.entry(offset);
+                (current_entry, offset)
+            };
+            self.current_node = Some(node);
+            self.offset = offset;
+            Some(current_entry)
+        } else {
+            None
+        }
+    }
+
+    /// Load the `XEntry` at the current cursor index within the `XArray`.
+    ///
+    /// Returns a reference to the `XEntry` at the target index if succeed.
+    /// If the cursor cannot reach to the target index, the method will return `None`.
+    pub(crate) fn load(&mut self) -> Option<&'a XEntry<I>> {
+        if let Some(node) = self.xa.head().as_node() {
+            if (self.index >> node.height()) as u64 > SLOT_MASK as u64 {
+                self.current_node = None;
+                return None;
+            }
+        } else {
+            return None;
+        }
+
+        // # Safety
+        // Because there won't be another concurrent modification operation, the `current_entry` is valid.
+        let mut current_entry = RefEntry::<'a>::new(self.xa.head());
+        while let Some(node) = unsafe { current_entry.as_entry().as_node() } {
+            if node.height() == 0 {
+                break;
+            }
+            current_entry = unsafe { self.move_to(current_entry.as_entry()).unwrap() };
+        }
+        unsafe {
+            self.move_to(current_entry.as_entry())
+                .map(|ref_entry| ref_entry.as_entry())
+        }
+    }
+
+    /// Initialize the Cursor to its initial state.
+    fn init(&mut self) {
+        self.current_node = None;
+        self.offset = 0;
+    }
+
+    /// Return the target index of the cursor.
+    fn index(&mut self) -> u64 {
+        self.index
+    }
+}
+
+/// A `CursorMut` can traverse in the `XArray` and have a target operated `XEntry`, which is stored in the `index` of `XArray`.
+/// `Cursor` can be only created by an `XArray`, and will hold its mutable reference, and can perform read and write operations
+/// for the corresponding `XArray`.
+/// When a cursor traverses an XArray, at any given moment, it is positioned on an XNode. If not, it means that
+/// the cursor has not begin to traverse. Its member `offset` indicates the next XEntry it will move to, which is the `slots[offset]` inside the current XNode.
+///
+/// When a CursorMut doing operation on XArray, it should not be affected by other CursorMuts or affect other Cursors.
+pub(crate) struct CursorMut<'a, I>
+where
+    I: ItemEntry,
+{
+    /// The `XArray` the cursor located in.
+    xa: &'a mut XArray<I>,
+    /// The target index of the cursor in the belonged `XArray`.
+    index: u64,
+    /// The next XEntry to be operated on is at 'offset' in the slots of the current XNode.
+    offset: u8,
+    /// Current positioned XNode.
+    current_node: Option<&'a XNode<I, ReadWrite>>,
+    _marker: PhantomData<I>,
+}
+
+impl<'a, I: ItemEntry> CursorMut<'a, I> {
+    /// Create an `CursorMut` to perform read and write operations on the `XArray`.
+    pub(crate) fn new(xa: &'a mut XArray<I>, index: u64) -> Self {
+        Self {
+            xa,
+            index,
+            offset: 0,
+            current_node: None,
+            _marker: PhantomData,
+        }
+    }
+
+    /// Move the `CursorMut` to the `XNode` that `node_entry` points to, and update the cursor's state based on its target index.
+    /// Return a reference to the `XEntry` within the slots of the current XNode that needs to be operated on next.
+    fn move_to(&mut self, node_entry: &'a XEntry<I>) -> Option<RefEntry<'a, I>> {
+        if let Some(node) = node_entry.as_node_mut() {
+            let (current_entry, offset) = {
+                let offset = node.entry_offset(self.index);
+                let current_entry = node.entry(offset);
+                (current_entry, offset)
+            };
+            self.current_node = Some(node);
+            self.offset = offset;
+            Some(current_entry)
+        } else {
+            None
+        }
+    }
+
+    /// Load the `XEntry` at the current cursor index within the `XArray`.
+    ///
+    /// Returns a reference to the `XEntry` at the target index if succeed.
+    /// If the cursor cannot reach to the target index, the method will return `None`.
+    pub(crate) fn load(&mut self) -> Option<&'a XEntry<I>> {
+        if let Some(node) = self.xa.head().as_node() {
+            if (self.index >> node.height()) as u64 > SLOT_MASK as u64 {
+                self.current_node = None;
+                return None;
+            }
+        } else {
+            return None;
+        }
+        // # Safety
+        // Because there won't be another concurrent modification operation, the `current_entry` is valid.
+        let mut current_entry = RefEntry::<'a>::new(self.xa.head());
+        while let Some(node) = unsafe { current_entry.as_entry().as_node() } {
+            if node.height() == 0 {
+                break;
+            }
+            current_entry = unsafe { self.move_to(current_entry.as_entry()).unwrap() };
+        }
+        unsafe {
+            self.move_to(current_entry.as_entry())
+                .map(|ref_entry| ref_entry.as_entry())
+        }
+    }
+
+    /// Stores the provided `XEntry` in the `XArray` at the position indicated by the current cursor index.
+    ///
+    /// If the provided entry is the same as the current entry at the cursor position,
+    /// the method returns the provided entry without making changes.
+    /// Otherwise, it replaces the current entry with the provided one and returns the old entry.
+    pub(crate) fn store(&mut self, entry: XEntry<I>) -> XEntry<I> {
+        let current_entry = self.traverse();
+        if entry.raw() == current_entry.raw() {
+            return entry;
+        }
+        let node = self.current_node.unwrap();
+        let old_entry = node.set_entry(self.offset, entry);
+        return old_entry;
+    }
+
+    /// Removes the `XEntry` at the target index of the 'CursorMut' within the `XArray`.
+    ///
+    /// This is achieved by storing an empty `XEntry` at the target index using the `store` method.
+    /// The method returns the replaced `XEntry` that was previously stored at the target index.
+    pub(crate) fn remove(&mut self) -> XEntry<I> {
+        self.store(XEntry::EMPTY)
+    }
+
+    /// Traverse the subtree based on the target index starting from the head node.
+    /// Move continuously until reaching the `XNode` capable of storing the target index.
+    /// It then returns the reference to the `XEntry` stored in the slot corresponding to the target index.
+    /// A target operated XEntry must be an item entry.
+    ///
+    /// Before traverse, the cursor will first expand the height of `XArray` to make sure it have enough capacity.
+    /// During the traverse, the cursor will allocate new `XNode` and put it in the appropriate slot if needed.
+    fn traverse(&mut self) -> &'a XEntry<I> {
+        let mut current_height = self.expand_height();
+        let mut ref_entry = RefEntry::<'a>::new(self.xa.head_mut());
+        // When the target entry has not been reached, the cursor will continue to move downward,
+        // and if it encounters a situation where there is no XNode, it will allocate an XNode.
+        //
+        // # Safety
+        // Because there won't be another concurrent modification operation, the `ref_entry` is valid.
+        while current_height > 0 {
+            let current_entry = unsafe { self.move_to(ref_entry.as_entry()).unwrap().as_entry() };
+            current_height -= NODE_HEIGHT as u8;
+            if let None = current_entry.as_node() {
+                let new_entry = {
+                    let new_owned_entry = self.alloc_node(current_height, self.offset);
+                    let node = self.current_node.unwrap();
+                    let _ = node.set_entry(self.offset, new_owned_entry);
+                    node.entry(self.offset)
+                };
+                ref_entry = new_entry;
+            } else {
+                ref_entry = RefEntry::<'a>::new(current_entry);
+            }
+        }
+        let k = unsafe { self.move_to(ref_entry.as_entry()).unwrap().as_entry() };
+        k
+    }
+
+    /// Increase the height of XArray to expand its capacity, allowing it to accommodate the target index,
+    /// and returns the height of the final head node.
+    ///
+    /// If the head node of the XArray does not exist, allocate a new head node of appropriate height directly.
+    /// Otherwise, if needed, repeatedly insert new nodes on top of the current head node to serve as the new head.
+    fn expand_height(&mut self) -> u8 {
+        if self.xa.head().is_null() {
+            let mut head_height = 0;
+            while (self.index >> head_height) as usize >= SLOT_SIZE {
+                head_height += NODE_HEIGHT as u8;
+            }
+            let head = self.alloc_node(head_height, 0);
+            self.xa.set_head(head);
+            return head_height;
+        } else {
+            loop {
+                let (capacity, head_height) = {
+                    let head = self.xa.head().as_node().unwrap();
+                    (head.max_index(), head.height())
+                };
+
+                if capacity > self.index {
+                    return head_height;
+                }
+
+                let new_node = self.alloc_node(head_height + NODE_HEIGHT as u8, 0);
+                let old_head_entry = self.xa.set_head(new_node);
+
+                let new_head = self.xa.head_mut().as_node_mut().unwrap();
+                let _empty = new_head.set_entry(0, old_head_entry);
+            }
+        }
+    }
+
+    /// Allocate a new XNode with the specified height and offset,
+    /// then generate a node entry from it and return it to the caller.
+    fn alloc_node(&mut self, height: u8, offset: u8) -> XEntry<I> {
+        XEntry::from_node(XNode::<I, ReadWrite>::new(height, offset))
+    }
+
+    /// Initialize the Cursor to its initial state.
+    fn init(&mut self) {
+        self.current_node = None;
+        self.offset = 0;
+    }
+
+    /// Return the target index of the cursor.
+    pub(crate) fn index(&mut self) -> u64 {
+        self.index
+    }
+}

src/entry.rs

@@ -1,161 +1,72 @@
-use std::{
-    marker::PhantomData,
-    mem::{self, ManuallyDrop, MaybeUninit},
-    sync::{Arc, RwLock},
-};
+use core::{marker::PhantomData, mem::ManuallyDrop, ptr::NonNull};
+use std::sync::{Arc, Mutex};
 
 use crate::*;
 
-/// 用来抽象用户将要存入XArray的指针类型
-/// 可以为诸如Arc、Box等实现，用户也可以自己为自定义的指针类型实现该trait
-pub trait PointerItem {
-    /// 将原有的指针类型转化为一个裸指针
+/// A trait that should be implemented for the types users wish to store in an `XArray`.
+/// Items stored in an XArray are required to be 4 bytes in size, Currently it can be various pointer types.
+pub trait ItemEntry {
+    /// Converts the original type into a `usize`, consuming the ownership of the original type.
     ///
-    /// # Safety
-    /// 用户需要确保该裸指针与原指针在内存布局上一致
-    /// 也就是原指针大小跟裸指针大小一致，且指向的位置一致
-    /// 同时需要确保原指针是aligned to 4的，因为XArray中的entry后两位要用于entry类型判断。
-    unsafe fn into_raw(self) -> *const u8;
-
-    /// 将一个裸指针转化为原指针
-    ///
-    /// # Safety
-    /// 裸指针必须是由同类型trait里的into_raw方法生成得到的，需要注意此时所有权的恢复。
-    unsafe fn from_raw(ptr: *const u8) -> Self;
-}
-
-impl<T> PointerItem for Box<T> {
-    unsafe fn into_raw(self) -> *const u8 {
-        let raw_ptr = Box::into_raw(self) as *const u8;
-        debug_assert!(raw_ptr.is_aligned_to(4));
-        raw_ptr
-    }
-
-    unsafe fn from_raw(ptr: *const u8) -> Self {
-        Box::from_raw(ptr as *mut _)
-    }
-}
-
-impl<T> PointerItem for Arc<T> {
-    unsafe fn into_raw(self) -> *const u8 {
-        let raw_ptr = unsafe { core::intrinsics::transmute::<Arc<T>, *const u8>(self) };
-        debug_assert!(raw_ptr.is_aligned_to(4));
-        raw_ptr
-    }
-
-    unsafe fn from_raw(ptr: *const u8) -> Self {
-        let arc = core::intrinsics::transmute::<*const u8, Arc<T>>(ptr);
-        arc
-    }
-}
-
-/// 用来抽象用户将要存入XArray的类型，这些存入XArray的obj称之为item。
-/// 对于存入的item，要求其大小为4字节，可以是各种指针类型或者是usize、u64等整数类型。
-pub(crate) trait ItemEntry {
-    /// 用户读取存储Item时的返回类型
-    type Target<'a>
-    where
-        Self: 'a;
-
-    /// 由原类型生成usize，消耗原类型所有权，该usize将直接存入XArray的XEntry。
-    /// 用户需要确保生产的usize符合XArray对item entry的要求，即如果原类型是pointer的话
-    /// 后两位为00，如果原类型是usize之类的value的话末位为1.
+    /// This `usize` should be directly stored in an XArray's XEntry. Users must ensure that the
+    /// produced `usize` meets the requirements for an item entry in the XArray. Specifically,
+    /// if the original type is a pointer, the last two bits should be 00; if the original
+    /// type is a value like usize, the last bit should be 1 (TODO).
     fn into_raw(self) -> usize;
 
-    /// 由usize恢复原类型，恢复所有权
+    /// Recovers the original type from a usize, reclaiming ownership.
     ///
     /// # Safety
-    /// 传入的raw必须是由同类型trait内对应方法into_raw生成的
+    /// The raw value passed must have been produced by the corresponding `into_raw` method in this trait
+    /// from the same type.
     unsafe fn from_raw(raw: usize) -> Self;
-
-    /// 读取该类型对应的XEntry，返回用户需要的读取类型
-    ///
-    /// # Safety
-    /// 需要确保entry是一个item_entry，同时需要确保原类型仍有效
-    unsafe fn load_item<'a>(entry: &'a XEntry) -> Self::Target<'a>;
 }
 
-impl<I: PointerItem> ItemEntry for I {
-    type Target<'a> = &'a Self where Self: 'a;
-
+impl<T> ItemEntry for Arc<T> {
     fn into_raw(self) -> usize {
-        let raw_ptr = unsafe { I::into_raw(self) };
+        let raw_ptr = unsafe { core::intrinsics::transmute::<Arc<T>, *const u8>(self) };
+        debug_assert!(raw_ptr.is_aligned_to(4));
         raw_ptr as usize
     }
 
     unsafe fn from_raw(raw: usize) -> Self {
-        I::from_raw(raw as *const u8)
-    }
-
-    unsafe fn load_item<'a>(entry: &'a XEntry) -> Self::Target<'a> {
-        debug_assert!(entry.is_item());
-        &*(entry as *const XEntry as *const I)
+        let arc = core::intrinsics::transmute::<usize, Arc<T>>(raw);
+        arc
     }
 }
 
-impl ItemEntry for usize {
-    type Target<'a> = usize;
-
+impl<T> ItemEntry for Box<T> {
     fn into_raw(self) -> usize {
-        debug_assert!(self <= usize::MAX >> 1);
-        (self << 1) | 1
+        let raw_ptr = Box::into_raw(self) as *const u8;
+        debug_assert!(raw_ptr.is_aligned_to(4));
+        raw_ptr as usize
     }
 
     unsafe fn from_raw(raw: usize) -> Self {
-        raw >> 1
-    }
-
-    unsafe fn load_item<'a>(entry: &'a XEntry) -> Self::Target<'a> {
-        Self::from_raw(entry.raw)
+        Box::from_raw(raw as *mut _)
     }
 }
 
-pub(crate) struct Item {}
-
-pub(crate) struct Node {}
-
-/// XArray中有所有权的Entry，只有两种Type，Item以及Node，分别对应ItemEntry以及指向Node的Entry
-/// 指向Node的Entry目前有统一的结构类型，也就是Arc<RwLock<XNode<I>>>。
-/// OwnedEntry目前只会在三种情况下生成:
-/// - store时由传入的item生成
-/// - 创建新的Node节点时生成
-/// - replace XArray上的XEntry时，将XEntry恢复成原来的OwnedEntry (该XEntry是由OwnedEntry生成的)
-#[derive(Eq)]
-#[repr(transparent)]
-pub struct OwnedEntry<I: ItemEntry, Type> {
+/// The type stored in the head of `XArray` and the slots of `XNode`s, which is the basic unit of storage within an XArray.
+/// There are the following types of `XEntry`:
+/// - Internal entries: These are invisible to users and have the last two bits set to 10. Currently `XArray` only have node
+/// entries as internal entries, which are entries that point to XNodes.
+/// - Item entries: Items stored by the user. Currently stored items can only be pointers and the last two bits
+/// of these item entries are 00.
+///
+/// `XEntry` have the ownership. Once it generated from an item or a XNode, the ownership of the item or the XNode
+/// will be transferred to the `XEntry`. If the stored item in the XArray implemented Clone trait, then the XEntry
+/// in the XArray can also implement Clone trait.
+#[derive(Eq, Debug)]
+pub(crate) struct XEntry<I>
+where
+    I: ItemEntry,
+{
     raw: usize,
-    _marker: core::marker::PhantomData<(I, Type)>,
-}
-
-impl<I: ItemEntry, Type> PartialEq for OwnedEntry<I, Type> {
-    fn eq(&self, o: &Self) -> bool {
-        self.raw == o.raw
-    }
+    _marker: core::marker::PhantomData<I>,
 }
 
-impl<I: ItemEntry + Clone> Clone for OwnedEntry<I, Item> {
-    fn clone(&self) -> Self {
-        let cloned_entry = unsafe {
-            let item_entry = ManuallyDrop::new(I::from_raw(self.raw));
-            OwnedEntry::from_item((*item_entry).clone())
-        };
-        return cloned_entry;
-    }
-}
-
-impl<I: ItemEntry> Clone for OwnedEntry<I, Node> {
-    fn clone(&self) -> Self {
-        unsafe {
-            Arc::increment_strong_count((self.raw - 2) as *const RwLock<XNode<I>>);
-        }
-        Self {
-            raw: self.raw,
-            _marker: core::marker::PhantomData,
-        }
-    }
-}
-
-impl<I: ItemEntry, Type> Drop for OwnedEntry<I, Type> {
+impl<I: ItemEntry> Drop for XEntry<I> {
     fn drop(&mut self) {
         if self.is_item() {
             unsafe {
@@ -164,75 +75,51 @@ impl<I: ItemEntry, Type> Drop for OwnedEntry<I, Type> {
         }
         if self.is_node() {
             unsafe {
-                Arc::from_raw((self.raw - 2) as *const RwLock<XNode<I>>);
+                Arc::from_raw((self.raw - 2) as *const XNode<I>);
             }
         }
     }
 }
 
-impl<I: ItemEntry> OwnedEntry<I, Item> {
-    pub(crate) fn into_raw(self) -> XEntry {
-        let raw_entry = XEntry { raw: self.raw };
-        let _ = ManuallyDrop::new(self);
-        raw_entry
-    }
-
-    pub(crate) fn from_raw(raw_entry: XEntry) -> Option<Self> {
-        if raw_entry.is_item() {
-            Some(Self {
-                raw: raw_entry.raw,
-                _marker: PhantomData,
-            })
+impl<I: ItemEntry + Clone> Clone for XEntry<I> {
+    fn clone(&self) -> Self {
+        if self.is_item() {
+            let cloned_entry = unsafe {
+                let item_entry = ManuallyDrop::new(I::from_raw(self.raw));
+                XEntry::from_item((*item_entry).clone())
+            };
+            cloned_entry
         } else {
-            None
+            if self.is_node() {
+                unsafe {
+                    Arc::increment_strong_count((self.raw - 2) as *const Mutex<XNode<I>>);
+                }
+            }
+            Self {
+                raw: self.raw,
+                _marker: core::marker::PhantomData,
+            }
         }
     }
-
-    pub(crate) fn from_item(item: I) -> Self {
-        let raw = I::into_raw(item);
-        Self::new(raw as usize)
-    }
 }
 
-impl<I: ItemEntry> OwnedEntry<I, Node> {
-    pub(crate) fn into_raw(self) -> XEntry {
-        let raw_entry = XEntry { raw: self.raw };
-        let _ = ManuallyDrop::new(self);
-        raw_entry
-    }
-
-    pub(crate) fn from_raw(raw_entry: XEntry) -> Option<Self> {
-        if raw_entry.is_node() {
-            Some(Self {
-                raw: raw_entry.raw,
-                _marker: PhantomData,
-            })
-        } else {
-            None
-        }
+impl<I: ItemEntry> PartialEq for XEntry<I> {
+    fn eq(&self, o: &Self) -> bool {
+        self.raw == o.raw
     }
+}
 
-    pub(crate) fn from_node(node: XNode<I>) -> Self {
-        let node_ptr = {
-            let arc_node = Arc::new(RwLock::new(node));
-            Arc::into_raw(arc_node)
-        };
-        Self::new(node_ptr as usize | 2)
+impl<I: ItemEntry> XEntry<I> {
+    pub(crate) fn raw(&self) -> usize {
+        self.raw
     }
 
-    pub(crate) fn as_node(&self) -> &RwLock<XNode<I>> {
-        unsafe {
-            let node_ref = &*((self.raw - 2) as *const RwLock<XNode<I>>);
-            node_ref
-        }
-    }
-}
+    pub(crate) const EMPTY: Self = Self::new(0);
 
-impl<I: ItemEntry, Type> OwnedEntry<I, Type> {
     pub(crate) const fn new(raw: usize) -> Self {
         Self {
             raw,
-            _marker: core::marker::PhantomData,
+            _marker: PhantomData,
         }
     }
 
@@ -249,71 +136,47 @@ impl<I: ItemEntry, Type> OwnedEntry<I, Type> {
     }
 
     pub(crate) fn is_node(&self) -> bool {
-        self.is_internal() && self.raw > (CHUNK_SIZE << 2)
-    }
-}
-
-/// 储存在XArray的head以及XNode的slots中的类型，XArray中存储的基本单位
-/// 有以下这样的类型分类
-/// - internal entries 用户不可见的内部entries 后两位bit为10
-///     - node entry 指向XNode的entry
-///     - sibling entry (用于multi-index entries), empty entry, retry entry (用于异常处理)
-/// - item entry 用户存储的item
-///     - pointer entry 后两位为00, (tagged pointer entry)
-///     - value entry 末位为1
-///
-/// XEntry没有所有权，可以copy，
-/// 指向XNode和表示Item的涉及到所有权的XEntry必须要由OwnedEntry调用into_raw获取，
-/// 这个操作只会发生在XArray的set_head以及XNode的set_slot过程中，
-/// 一获得XEntry就会将其存储在head或slot里，并将旧的XEntry恢复成OwnedEntry。
-/// 此操作相当于将OwnedEntry的所有权转移到了XArray和XNode上，
-/// 二者的drop期间需要负责将这些XEntry恢复成OwnedEntry
-///
-/// XArray和XNode的clone也要负责实际的OwnedEntry的clone
-///
-#[derive(Eq, Copy, Clone)]
-#[repr(transparent)]
-pub struct XEntry {
-    raw: usize,
-}
-
-impl PartialEq for XEntry {
-    fn eq(&self, o: &Self) -> bool {
-        self.raw == o.raw
-    }
-}
-
-impl XEntry {
-    pub(crate) const EMPTY: Self = Self::new(0);
-
-    pub(crate) const fn new(raw: usize) -> Self {
-        Self { raw }
+        self.is_internal() && self.raw > (SLOT_SIZE << 2)
     }
 
-    pub(crate) fn is_null(&self) -> bool {
-        self.raw == 0
-    }
-
-    pub(crate) fn is_internal(&self) -> bool {
-        self.raw & 3 == 2
+    pub(crate) fn from_item(item: I) -> Self {
+        let raw = I::into_raw(item);
+        Self::new(raw as usize)
     }
 
-    pub(crate) fn is_item(&self) -> bool {
-        !self.is_null() && !self.is_internal()
+    pub(crate) fn into_item(self) -> Option<I> {
+        if self.is_item() {
+            let item = unsafe { I::from_raw(self.raw) };
+            let _ = ManuallyDrop::new(self);
+            Some(item)
+        } else {
+            None
+        }
     }
 
-    pub(crate) fn is_node(&self) -> bool {
-        self.is_internal() && self.raw > (CHUNK_SIZE << 2)
+    pub(crate) fn from_node<Operation>(node: XNode<I, Operation>) -> Self {
+        let node_ptr = {
+            let arc_node = Arc::new(node);
+            Arc::into_raw(arc_node)
+        };
+        Self::new(node_ptr as usize | 2)
     }
 
-    pub(crate) fn is_sibling(&self) -> bool {
-        self.is_internal() && self.raw < (((CHUNK_SIZE - 1) << 2) | 2)
+    pub(crate) fn as_node(&self) -> Option<&XNode<I>> {
+        if self.is_node() {
+            unsafe {
+                let node_ref = &*((self.raw - 2) as *const XNode<I>);
+                Some(node_ref)
+            }
+        } else {
+            None
+        }
     }
 
-    pub(crate) fn as_node<I: ItemEntry>(&self) -> Option<&RwLock<XNode<I>>> {
+    pub(crate) fn as_node_mut<'a>(&self) -> Option<&'a XNode<I, ReadWrite>> {
         if self.is_node() {
             unsafe {
-                let node_ref = &*((self.raw - 2) as *const RwLock<XNode<I>>);
+                let node_ref = &*((self.raw - 2) as *const XNode<I, ReadWrite>);
                 Some(node_ref)
             }
         } else {
@@ -321,17 +184,53 @@ impl XEntry {
         }
     }
 
-    pub(crate) fn as_sibling(&self) -> Option<u8> {
-        if self.is_sibling() {
-            Some((self.raw >> 2).try_into().unwrap())
+    pub(crate) fn node_strong_count(&self) -> Option<usize> {
+        if self.is_node() {
+            let raw_ptr = (self.raw - 2) as *const u8;
+            unsafe {
+                let arc = Arc::from_raw(raw_ptr);
+                let strong_count = Arc::strong_count(&arc);
+                let _ = ManuallyDrop::new(arc);
+                Some(strong_count)
+            }
         } else {
             None
         }
     }
 }
 
-impl<I: ItemEntry, Type> PartialEq<OwnedEntry<I, Type>> for XEntry {
-    fn eq(&self, o: &OwnedEntry<I, Type>) -> bool {
-        self.raw == o.raw
+/// An immutable reference to an `XEntry` stored in the `head` of `XArray` or the slots of `XNode` with a lifetime `'a`.
+///
+/// It can be used as `&'a XEntry` during the `'a` lifetime through `as_entry()` method.  
+pub(crate) struct RefEntry<'a, I>
+where
+    I: ItemEntry,
+{
+    ref_ptr: NonNull<XEntry<I>>,
+    _marker: &'a (),
+}
+
+impl<'a, I: ItemEntry> RefEntry<'a, I> {
+    /// Create a `RefEntry` from an input `entry`. The lifetime of `entry` may be shorter than `'a`
+    /// since the `entry` may reference to a lock guard.
+    pub(crate) fn new(entry: &XEntry<I>) -> Self {
+        Self {
+            ref_ptr: NonNull::new(entry as *const XEntry<I> as *mut XEntry<I>).unwrap(),
+            _marker: &(),
+        }
+    }
+
+    /// Return as an `&'a XEntry`.
+    ///
+    /// # Safety
+    /// Ensure that during the lifetime of the `&'a XEntry`, no one modifies the referenced content.
+    pub(crate) unsafe fn as_entry(&self) -> &'a XEntry<I> {
+        &*self.ref_ptr.as_ptr()
     }
 }
+
+unsafe impl<I: ItemEntry + Sync> Sync for XEntry<I> {}
+unsafe impl<I: ItemEntry + Send> Send for XEntry<I> {}
+
+unsafe impl<'a, I: ItemEntry + Sync> Sync for RefEntry<'a, I> {}
+unsafe impl<'a, I: ItemEntry + Send> Send for RefEntry<'a, I> {}

src/lib.rs

@@ -0,0 +1,17 @@
+#![feature(pointer_is_aligned)]
+#![feature(specialization)]
+#![feature(associated_type_defaults)]
+
+use cow::*;
+use cursor::*;
+use entry::*;
+use node::*;
+pub use xarray::*;
+
+mod cow;
+mod cursor;
+mod entry;
+mod node;
+mod xarray;
+
+mod test;

src/main.rs

@@ -1,44 +0,0 @@
-#![feature(pointer_is_aligned)]
-use core::prelude::v1;
-use entry::*;
-use mark::*;
-use node::*;
-use state::*;
-use std::sync::Arc;
-use xarray::*;
-
-mod entry;
-mod mark;
-mod node;
-mod state;
-mod xarray;
-
-#[derive(Debug)]
-struct P {
-    x: usize,
-}
-
-impl Drop for P {
-    fn drop(&mut self) {
-        println!("drop");
-    }
-}
-
-fn main() {
-    let mut xarray_arc: XArray<Arc<P>, XMarkDemo> = XArray::new();
-    let v1 = Arc::new(P { x: 32 });
-    xarray_arc.store(130, v1);
-    let v1 = xarray_arc.load(130).unwrap();
-    println!("arc:{:?}", v1);
-
-    let mut xarray_usize: XArray<usize, XMarkDemo> = XArray::new();
-    xarray_usize.store(100, 10);
-    xarray_usize.store(8, 100);
-    let v1 = xarray_usize.load(100);
-    println!("load usize: {:?}", v1);
-    let v2 = xarray_usize.load(8);
-    println!("load usize: {:?}", v2);
-    xarray_usize.remove(8);
-    let v2 = xarray_usize.load(8);
-    println!("load usize: {:?}", v2);
-}

src/mark.rs

@@ -1,47 +0,0 @@
-use std::cmp::min;
-
-use crate::*;
-
-#[derive(Clone, Copy)]
-pub struct Mark {
-    pub inner: usize,
-}
-
-impl Mark {
-    pub fn set(&mut self, offset: usize) {
-        self.inner |= 1 << offset;
-    }
-
-    pub fn unset(&mut self, offset: usize) {
-        self.inner &= !(1 << offset);
-    }
-
-    pub fn is_marked(&self, offset: usize) -> bool {
-        (self.inner | 1 << offset) == 1
-    }
-}
-
-pub trait XMark {
-    fn index_raw(&self) -> usize;
-    fn index(&self) -> usize {
-        let index = self.index_raw();
-        debug_assert!(index < 3);
-        index
-    }
-}
-
-pub enum XMarkDemo {
-    Dirty,
-    COW,
-    LOCKED,
-}
-
-impl XMark for XMarkDemo {
-    fn index_raw(&self) -> usize {
-        match self {
-            XMarkDemo::Dirty => 0,
-            XMarkDemo::COW => 1,
-            XMarkDemo::LOCKED => 2,
-        }
-    }
-}

src/node.rs

@@ -1,115 +1,123 @@
-use std::{
-    marker::PhantomData,
-    sync::{Arc, Mutex, RwLock, Weak},
-};
+use std::{marker::PhantomData, sync::Mutex};
 
 use crate::*;
 
-/// XArray中的节点结构，每一个节点都由一个RwLock管理
-/// 其中shift、offset用于基本操作计算，count和nr_value服务于Multi-index entries
-pub struct XNode<I: ItemEntry> {
-    shift: u8,
-    offset: u8,
-    count: u8,
-    nr_value: u8,
-    parent: XEntry,
-    slots: [XEntry; CHUNK_SIZE],
-    marks: [Mark; 3],
-    _marker: PhantomData<I>,
+pub(crate) struct ReadOnly {}
+pub(crate) struct ReadWrite {}
+
+/// `XNode` is the intermediate node in the tree-like structure of XArray.
+///
+/// It contains `SLOT_SIZE` number of XEntries, meaning it can accommodate up to `SLOT_SIZE` child nodes.
+/// The 'height' and 'offset' attributes of an XNode are determined at initialization and remain unchanged thereafter.
+/// XNode has a generic parameter called 'Operation', which has two possible instances: `ReadOnly` and `ReadWrite`.
+/// These instances indicate whether the XNode will only perform read operations or both read and write operations
+/// (where write operations imply potential modifications to the contents of slots).
+pub(crate) struct XNode<I: ItemEntry, Operation = ReadOnly> {
+    /// The node's height from the bottom of the tree. The height of a lead node,
+    /// which stores the user-given items, is zero.
+    height: u8,
+    /// This node is its parent's `offset_in_parent`-th child.
+    /// This field is meaningless if this node is the root (will be 0).
+    offset_in_parent: u8,
+    inner: Mutex<XNodeInner<I>>,
+    _marker: PhantomData<Operation>,
 }
 
-impl<I: ItemEntry> XNode<I> {
-    pub(crate) fn new(shift: u8, offset: u8, parent: XEntry) -> Self {
+pub(crate) struct XNodeInner<I: ItemEntry> {
+    slots: [XEntry<I>; SLOT_SIZE],
+}
+
+impl<I: ItemEntry, Operation> XNode<I, Operation> {
+    pub(crate) fn new(height: u8, offset: u8) -> Self {
         Self {
-            shift,
-            offset,
-            count: 0,
-            nr_value: 0,
-            parent: parent,
-            slots: [XEntry::EMPTY; CHUNK_SIZE],
-            marks: [Mark { inner: 0 }; 3],
+            height,
+            offset_in_parent: offset,
+            inner: Mutex::new(XNodeInner::new()),
             _marker: PhantomData,
         }
     }
 
-    pub(crate) fn mark_mut(&mut self, index: usize) -> &mut Mark {
-        &mut self.marks[index]
-    }
-
-    pub(crate) fn mark(&self, index: usize) -> &Mark {
-        &self.marks[index]
+    /// Get the offset in the slots of the current XNode corresponding to the XEntry for the target index.
+    pub(crate) const fn entry_offset(&self, target_index: u64) -> u8 {
+        ((target_index >> self.height as u64) & SLOT_MASK as u64) as u8
     }
 
-    pub(crate) const fn get_offset(&self, index: u64) -> u8 {
-        ((index >> self.shift as u64) & CHUNK_MASK as u64) as u8
+    /// Get the max index the XNode and its child nodes can store.
+    pub(crate) fn max_index(&self) -> u64 {
+        ((SLOT_SIZE as u64) << (self.height as u64)) - 1
     }
 
-    pub(crate) fn entry(&self, index: u8) -> &XEntry {
-        &self.slots[index as usize]
+    pub(crate) fn height(&self) -> u8 {
+        self.height
     }
 
-    pub(crate) fn set_node_entry(
-        &mut self,
-        offset: u8,
-        entry: OwnedEntry<I, Node>,
-    ) -> Option<OwnedEntry<I, Node>> {
-        let old_entry = OwnedEntry::<I, Node>::from_raw(self.slots[offset as usize]);
-        self.slots[offset as usize] = OwnedEntry::<I, Node>::into_raw(entry);
-        old_entry
-    }
-
-    pub(crate) fn set_item_entry(
-        &mut self,
-        offset: u8,
-        entry: Option<OwnedEntry<I, Item>>,
-    ) -> Option<OwnedEntry<I, Item>> {
-        let old_entry = OwnedEntry::<I, Item>::from_raw(self.slots[offset as usize]);
-        let new_entry = entry
-            .map(|entry| OwnedEntry::<I, Item>::into_raw(entry))
-            .unwrap_or(XEntry::EMPTY);
-        self.slots[offset as usize] = new_entry;
-
-        old_entry
+    pub(crate) fn offset_in_parent(&self) -> u8 {
+        self.offset_in_parent
     }
+}
 
-    pub(crate) fn max_index(&self) -> u64 {
-        ((CHUNK_SIZE as u64) << (self.shift as u64)) - 1
+impl<I: ItemEntry> XNode<I, ReadOnly> {
+    pub(crate) fn entry<'a>(&'a self, offset: u8) -> RefEntry<'a, I> {
+        let lock = self.inner.lock().unwrap();
+        let entry = lock.entry(offset);
+        RefEntry::new(entry)
     }
+}
 
-    pub(crate) fn shift(&self) -> u8 {
-        self.shift
+impl<I: ItemEntry> XNode<I, ReadWrite> {
+    pub(crate) fn entry<'a>(&'a self, offset: u8) -> RefEntry<'a, I> {
+        let mut lock = self.inner.lock().unwrap();
+        let entry = lock.entry_mut(offset);
+        RefEntry::new(entry)
     }
 
-    pub(crate) fn offset(&self) -> u8 {
-        self.offset
+    pub(crate) fn set_entry(&self, offset: u8, entry: XEntry<I>) -> XEntry<I> {
+        self.inner.lock().unwrap().set_entry(offset, entry)
     }
+}
 
-    pub(crate) fn parent(&self) -> XEntry {
-        self.parent
+impl<I: ItemEntry> XNodeInner<I> {
+    pub(crate) fn new() -> Self {
+        Self {
+            slots: [XEntry::EMPTY; SLOT_SIZE],
+        }
     }
 
-    pub(crate) fn set_offset(&mut self, offset: u8) {
-        self.offset = offset;
+    pub(crate) fn entry(&self, offset: u8) -> &XEntry<I> {
+        &self.slots[offset as usize]
     }
 
-    pub(crate) fn set_parent(&mut self, parent: XEntry) {
-        self.parent = parent;
+    pub(crate) fn entry_mut(&mut self, offset: u8) -> &XEntry<I> {
+        // When a modification to the target entry is needed, it first checks whether the entry is shared with other XArrays.
+        // If it is, then it performs a copy-on-write by allocating a new entry and using it,
+        // to prevent the modification from affecting the read or write operations on other XArrays.
+        self.copy_on_write(
+            unsafe { &*(&self.slots[offset as usize] as *const XEntry<I>) },
+            offset,
+        )
     }
 
-    pub(crate) fn set_shift(&mut self, shift: u8) {
-        self.shift = shift;
+    pub(crate) fn set_entry(&mut self, offset: u8, entry: XEntry<I>) -> XEntry<I> {
+        let old_entry = core::mem::replace(&mut self.slots[offset as usize], entry);
+        old_entry
     }
 }
 
-impl<I: ItemEntry> Drop for XNode<I> {
-    fn drop(&mut self) {
-        for entry in self.slots {
-            if entry.is_node() {
-                OwnedEntry::<I, Node>::from_raw(entry);
-            }
-            if entry.is_item() {
-                OwnedEntry::<I, Item>::from_raw(entry);
-            }
+pub(crate) fn deep_clone_node_entry<I: ItemEntry + Clone>(entry: &XEntry<I>) -> XEntry<I> {
+    debug_assert!(entry.is_node());
+    let new_node = {
+        let cloned_node: &XNode<I> = entry.as_node().unwrap();
+        let new_node =
+            XNode::<I, ReadWrite>::new(cloned_node.height(), cloned_node.offset_in_parent());
+        let mut new_node_lock = new_node.inner.lock().unwrap();
+        let cloned_node_lock = cloned_node.inner.lock().unwrap();
+        for i in 0..SLOT_SIZE {
+            let entry = &cloned_node_lock.slots[i];
+            let new_entry = entry.clone();
+            new_node_lock.slots[i as usize] = new_entry;
         }
-    }
+        drop(new_node_lock);
+        new_node
+    };
+    XEntry::from_node(new_node)
 }

src/state.rs

@@ -1,240 +0,0 @@
-use std::{
-    marker::PhantomData,
-    sync::{Arc, RwLock, Weak},
-};
-
-use crate::*;
-
-pub enum CurrentState {
-    Empty,
-    Bound,
-    Restart,
-    Node(XEntry),
-}
-
-impl CurrentState {
-    pub(crate) fn get<I: ItemEntry>(&self) -> Option<&RwLock<XNode<I>>> {
-        if let Self::Node(node) = self {
-            node.as_node()
-        } else {
-            None
-        }
-    }
-
-    pub(crate) fn is_empty(&self) -> bool {
-        matches!(self, Self::Empty)
-    }
-
-    pub(crate) fn is_restart(&self) -> bool {
-        matches!(self, Self::Restart)
-    }
-
-    pub(crate) fn is_bound(&self) -> bool {
-        matches!(self, Self::Bound)
-    }
-}
-
-pub struct State<I: ItemEntry, M: XMark> {
-    pub index: u64,
-    pub shift: u8,
-    pub sibs: u8,
-    pub offset: u8,
-    pub node: CurrentState,
-    _marker: PhantomData<(I, M)>,
-}
-
-/// 一个时刻只能获得一个node的写锁
-impl<I: ItemEntry, M: XMark> State<I, M> {
-    pub fn new(index: u64) -> Self {
-        State {
-            index,
-            shift: 0,
-            sibs: 0,
-            offset: 0,
-            node: CurrentState::Restart,
-            _marker: PhantomData,
-        }
-    }
-
-    /// xa_state移动到目标node_entry, 返回在当前node中，对应index应该操作的下一个entry。
-    fn move_to<'a>(&mut self, node_entry: XEntry) -> Option<&'a XEntry> {
-        if let Some(node) = node_entry.as_node::<I>() {
-            let node_read = node.read().unwrap();
-            let offset = node_read.get_offset(self.index);
-            let op_entry = node_read.entry(offset);
-            // if let Some(sib) = entry.as_sibling() {
-            //     offset = sib;
-            //     op_entry = node_read.entry(offset);
-            // }
-            self.node = CurrentState::Node(node_entry);
-            self.offset = offset;
-            unsafe { Some(&*(op_entry as *const XEntry)) }
-        } else {
-            None
-        }
-    }
-
-    pub fn load<'a>(&mut self, xa: &'a XArray<I, M>) -> &'a XEntry {
-        let mut current_node = self.node.get::<I>();
-        let mut op_entry = {
-            if let Some(node) = current_node {
-                let node_read = node.read().unwrap();
-                let op_entry = node_read.entry(self.offset);
-                *op_entry
-            } else {
-                if let Some(node) = xa.head().as_node::<I>() {
-                    let node_read = node.read().unwrap();
-                    if (self.index >> node_read.shift()) as u64 > CHUNK_MASK as u64 {
-                        self.node = CurrentState::Bound;
-                        XEntry::EMPTY
-                    } else {
-                        *xa.head()
-                    }
-                } else {
-                    XEntry::EMPTY
-                }
-            }
-        };
-        while let Some(node) = op_entry.as_node::<I>() {
-            let node_read = node.read().unwrap();
-            if self.shift > node_read.shift() {
-                break;
-            }
-            if node_read.shift() == 0 {
-                break;
-            }
-            drop(node_read);
-            op_entry = *self.move_to(op_entry).unwrap();
-        }
-        self.move_to(op_entry).unwrap()
-    }
-
-    pub fn store(
-        &mut self,
-        xa: &mut XArray<I, M>,
-        entry: Option<OwnedEntry<I, Item>>,
-    ) -> Option<OwnedEntry<I, Item>> {
-        let op_entry = self.create(xa);
-        // TODO: Multi-index entry
-        if entry.as_ref().is_some_and(|entry| *op_entry == *entry) {
-            return entry;
-        }
-        let node = self.node.get().unwrap();
-        let mut node_write = node.write().unwrap();
-        let old_entry = node_write.set_item_entry(self.offset, entry);
-        return old_entry;
-    }
-
-    /// 不断创建新的Node, 直到得到目标index的entry
-    fn create(&mut self, xa: &mut XArray<I, M>) -> &XEntry {
-        let mut shift = 0;
-        // Normal
-        if let None = self.node.get::<I>() {
-            self.clear_state();
-            // 将当前的树先扩展为足够支持index储存的形式
-            // 此时self操作的node为head节点
-            shift = self.expand(xa);
-            self.move_to(*xa.head());
-        } else {
-            shift = self.shift;
-        }
-
-        let mut entry = {
-            let node = self.node.get::<I>().unwrap();
-            let node_read = node.read().unwrap();
-            *node_read.entry(self.offset)
-        };
-        while shift > 0 {
-            shift -= CHUNK_SHIFT as u8;
-            // if entry.is_item() {
-            //     break;
-            // }
-            if let None = entry.as_node::<I>() {
-                let node_entry = {
-                    let new_entry = self.alloc(shift);
-                    let node = self.node.get().unwrap();
-                    let mut node_write = node.write().unwrap();
-                    let _ = node_write.set_node_entry(self.offset, new_entry);
-                    *node_write.entry(self.offset)
-                };
-                entry = node_entry;
-            }
-            if shift <= 0 {
-                break;
-            }
-            entry = *self.move_to(entry).unwrap();
-        }
-        self.move_to(entry).unwrap()
-        // obsidian
-    }
-
-    /// 在根节点处增加若干节点，以增加树高。
-    /// array -> head -> ...
-    /// -> array -> new_node -> ... -> head -> ...
-    fn expand(&mut self, xa: &mut XArray<I, M>) -> u8 {
-        let mut shift = 0;
-        let mut capacity = 0;
-
-        // 有head node，则可以直接知道当前XArray的最大容纳量，shift赋值为当前最大shift + 6。
-        if let Some(node) = xa.head().as_node::<I>() {
-            let node_read = node.read().unwrap();
-            shift = node_read.shift() + CHUNK_SHIFT as u8;
-            capacity = node_read.max_index();
-        }
-        // 没有head的情况，则计算所需要的shift，直接返回，在上层函数直接create根节点，赋值相应shift进行存储。
-        else {
-            while (self.index >> shift) as usize >= CHUNK_SIZE {
-                shift += CHUNK_SHIFT as u8;
-            }
-            let head = self.alloc(shift);
-            capacity = max_index(shift);
-            xa.set_head(head);
-            return shift + CHUNK_SHIFT as u8;
-        }
-
-        // 指向空节点
-        self.clear_state();
-        while self.index > capacity {
-            // 创建一个新的head，原本的head作为新node的child
-            let node_entry = self.alloc(shift);
-            let old_head_entry = xa.set_head(node_entry).unwrap();
-            let new_head_entry = xa.head();
-
-            let mut head_write = old_head_entry.as_node().write().unwrap();
-            head_write.set_offset(0);
-            head_write.set_parent(*new_head_entry);
-            capacity = head_write.max_index();
-            drop(head_write);
-
-            let new_head_node = new_head_entry.as_node::<I>().unwrap();
-            let mut node_write = new_head_node.write().unwrap();
-            node_write.set_node_entry(0, old_head_entry);
-
-            shift += CHUNK_SHIFT as u8;
-        }
-        self.node = CurrentState::Node(*xa.head());
-        shift
-    }
-
-    /// Alloc a node entry as a slot for the XState operated node.
-    fn alloc(&mut self, shift: u8) -> OwnedEntry<I, Node> {
-        let (parent, offset) = {
-            if let CurrentState::Node(entry) = self.node {
-                (entry, self.offset)
-            } else {
-                (XEntry::EMPTY, 0)
-            }
-        };
-        debug_assert!(parent.is_null() || parent.is_node());
-        OwnedEntry::<I, Node>::from_node(XNode::new(shift, offset, parent))
-    }
-
-    fn clear_state(&mut self) {
-        self.node = CurrentState::Empty;
-        self.offset = 0;
-    }
-}
-
-fn max_index(shift: u8) -> u64 {
-    ((CHUNK_SIZE as u64) << (shift as u64)) - 1
-}

src/test.rs

@@ -0,0 +1,88 @@
+use super::*;
+use std::sync::Arc;
+
+#[test]
+fn test_store() {
+    let mut xarray_arc: XArray<Arc<i32>> = XArray::new();
+    for i in 1..10000 {
+        let value = Arc::new(i * 2);
+        xarray_arc.store((i * 3) as u64, value);
+    }
+    for i in 1..10000 {
+        let value = xarray_arc.load((i * 3) as u64).unwrap();
+        assert!(*value.as_ref() == i * 2)
+    }
+}
+
+#[test]
+fn test_remove() {
+    let mut xarray_arc: XArray<Arc<i32>> = XArray::new();
+    for i in 0..10000 {
+        let value = Arc::new(i * 2);
+        xarray_arc.store(i as u64, value);
+    }
+    for i in 0..10000 {
+        xarray_arc.remove(i as u64);
+        let value = xarray_arc.load(i as u64);
+        assert!(value == None)
+    }
+}
+
+#[test]
+fn test_cow() {
+    static mut INIT_COUNT: usize = 0;
+    static mut DROP_COUNT: usize = 0;
+    struct Wrapper {
+        raw: usize,
+    }
+
+    impl Drop for Wrapper {
+        fn drop(&mut self) {
+            unsafe {
+                DROP_COUNT += 1;
+            }
+        }
+    }
+
+    impl Wrapper {
+        fn new(raw: usize) -> Self {
+            unsafe {
+                INIT_COUNT += 1;
+            }
+            Self { raw }
+        }
+    }
+    let mut xarray_arc: XArray<Arc<Wrapper>> = XArray::new();
+    for i in 1..10000 {
+        let value = Arc::new(Wrapper::new(i * 2));
+        xarray_arc.store(i as u64, value);
+    }
+    let mut xarray_clone = xarray_arc.clone();
+
+    for i in 1..10000 {
+        if i % 2 == 0 {
+            let value = Arc::new(Wrapper::new(i * 6));
+            xarray_arc.store(i as u64, value);
+        } else {
+            let value = Arc::new(Wrapper::new(i * 8));
+            xarray_clone.store(i as u64, value);
+        }
+    }
+
+    for i in 1..10000 {
+        let value_origin = xarray_arc.load(i).unwrap();
+        let value_clone = xarray_clone.load(i).unwrap();
+        if i % 2 == 0 {
+            assert!(value_origin.raw as u64 == i * 6);
+            assert!(value_clone.raw as u64 == i * 2);
+        } else {
+            assert!(value_origin.raw as u64 == i * 2);
+            assert!(value_clone.raw as u64 == i * 8);
+        }
+    }
+    drop(xarray_arc);
+    drop(xarray_clone);
+    unsafe {
+        assert!(INIT_COUNT == DROP_COUNT);
+    }
+}

src/xarray.rs

@@ -1,35 +1,58 @@
-use std::{
-    marker::PhantomData,
-    sync::{Arc, Mutex, RwLock},
-};
+use std::marker::PhantomData;
 
 use crate::*;
-pub const CHUNK_SHIFT: usize = 6;
-pub const CHUNK_SIZE: usize = 1 << CHUNK_SHIFT;
-pub const CHUNK_MASK: usize = CHUNK_SIZE - 1;
+
+pub(crate) const NODE_HEIGHT: usize = 6;
+pub(crate) const SLOT_SIZE: usize = 1 << NODE_HEIGHT;
+pub(crate) const SLOT_MASK: usize = SLOT_SIZE - 1;
 
 /// The XArray is an abstract data type which behaves like a very large array of items.
-/// Items here must be a 8 bytes object, like pointers or `u64`.
-/// it allows you to sensibly go to the next or previous entry in a cache-efficient manner.
-/// Normal pointers may be stored in the XArray directly. They must be 4-byte aligned.
+/// Items here must be a 8 bytes object, like `Arc<T>` and `Box<T>`.
+/// The alignment of the pointers stored by users must be at least 4.
+/// It allows you to sensibly go to the next or previous entry in a cache-efficient manner.
+/// It allows multiple concurrent reads of the XArray, but only permits one write operation on the XArray at any given time.
+///
+/// # Features
+/// **Copy-on-write (COW).** If the item stored in `XArray` implemented `Clone` trait, the `XArray`
+/// can achieve Clone with a COW mechanism. When cloning an XArray, initially the new XArray shares a head with the original XArray
+/// without performing an actual clone. If either of the XArrays needs to perform a mutable operation, a substantive clone of the XNode to be modified is created before making the update.
+/// This ensures that operations on the two XArrays do not affect each other.
+/// **Reference.** All operations on XArray are performed through `Cursor` and `CursorMut`. 
+/// Cursor requires an immutable reference to XArray, while CursorMut requires a mutable reference. 
+/// Therefore, XArray can have multiple Cursors operating at the same time, whereas the operations of CursorMut are exclusive (similar to the relationship between & and &mut).
 ///
 /// # Example
 ///
 /// ```
-/// let mut xarray_arc: XArray<Arc<i32>, XMarkDemo> = XArray::new();
-/// let v1 = Arc::new(10);
-/// xarray_arc.store(333, v1);
-/// assert!(xarray_arc.load(333).unwrap() == 10);
+/// use std::sync::Arc;
+/// use xarray::*;
+///
+/// let mut xarray_arc: XArray<Arc<i32>> = XArray::new();
+/// let value = Arc::new(10);
+/// xarray_arc.store(333, value);
+/// assert!(*xarray_arc.load(333).unwrap().as_ref() == 10);
+///
+/// let mut xarray_clone = xarray_arc.clone();
+/// assert!(*xarray_clone.load(333).unwrap().as_ref() == 10);
+/// let value = Arc::new(100);
+/// xarray_clone.store(333, value);
+///
+/// assert!(*xarray_arc.load(333).unwrap().as_ref() == 10);
+/// assert!(*xarray_clone.load(333).unwrap().as_ref() == 100);
 /// ```
 ///
-/// It can support storing a range of indices at once （Multi-index entries, TODO）.
-/// It also supports a marking function, allowing for the stored contents to be marked with the required labels (TODO).
-pub struct XArray<I: ItemEntry, M: XMark> {
-    head: XEntry,
-    _marker: PhantomData<(I, M)>,
+/// The concepts XArray are originally introduced by Linux, which keeps the data structure of Linux's radix tree
+/// [Linux Radix Trees](https://lwn.net/Articles/175432/).
+pub struct XArray<I>
+where
+    I: ItemEntry,
+{
+    head: XEntry<I>,
+    _marker: PhantomData<I>,
 }
 
-impl<I: ItemEntry, M: XMark> XArray<I, M> {
+impl<I: ItemEntry> XArray<I> {
+    /// Make a new, empty XArray.
     pub const fn new() -> Self {
         Self {
             head: XEntry::EMPTY,
@@ -37,96 +60,70 @@ impl<I: ItemEntry, M: XMark> XArray<I, M> {
         }
     }
 
-    pub(crate) fn head(&self) -> &XEntry {
+    /// Return a reference to the head entry, and later will not modify the XNode pointed to by the `head`.
+    pub(crate) fn head(&self) -> &XEntry<I> {
         &self.head
     }
 
-    pub(crate) fn set_head(&mut self, head: OwnedEntry<I, Node>) -> Option<OwnedEntry<I, Node>> {
-        let old_head = OwnedEntry::<I, Node>::from_raw(self.head);
-        self.head = OwnedEntry::<I, Node>::into_raw(head);
+    /// Return a reference to the head entry, and later will modify the XNode pointed to by the `head`.
+    pub(crate) fn head_mut(&mut self) -> &XEntry<I> {
+        // When a modification to the head is needed, it first checks whether the head is shared with other XArrays.
+        // If it is, then it performs a copy-on-write by allocating a new head and using it,
+        // to prevent the modification from affecting the read or write operations on other XArrays.
+        self.copy_on_write(unsafe { &*(&self.head as *const XEntry<I>) }, 0)
+    }
+
+    /// Set the head of the `XArray` with the new `XEntry`, and return the old `head`.
+    pub(crate) fn set_head(&mut self, head: XEntry<I>) -> XEntry<I> {
+        let old_head = core::mem::replace(&mut self.head, head);
         old_head
     }
 
-    pub fn load<'a>(&'a self, index: u64) -> Option<I::Target<'a>> {
+    /// Attempts to load the item at the target index within the `XArray`.
+    /// If the target item exists, return it with `Some`, Otherwise, return `None`.
+    pub fn load(&self, index: u64) -> Option<&I> {
         let mut cursor = self.cursor(index);
-        let entry = cursor.current();
-        if entry.is_item() {
-            unsafe { Some(I::load_item(entry)) }
-        }
-        else {
+        let entry = cursor.load();
+        if entry.is_some_and(|entry| entry.is_item()) {
+            entry.map(|entry| unsafe { &*(entry as *const XEntry<I> as *const I) })
+        } else {
             None
         }
     }
 
-    pub fn store(&mut self, index: u64, value: I) {
-        self.cursor_mut(index).store(value);
-    }
-
-    pub fn remove(&mut self, index: u64) {
-        self.cursor_mut(index).remove();
-    }
-
-    pub fn cursor<'a>(&'a self, index: u64) -> Cursor<'a, I, M> {
-        Cursor {
-            xa: self,
-            xas: State::new(index),
-        }
-    }
-
-    pub fn cursor_mut<'a>(&'a mut self, index: u64) -> CursorMut<'a, I, M> {
-        CursorMut {
-            xa: self,
-            xas: State::new(index),
-        }
+    /// Stores the provided item in the `XArray` at the target index,
+    /// and return the old item if it was previously stored in target index.
+    pub fn store(&mut self, index: u64, item: I) -> Option<I> {
+        let stored_entry = XEntry::from_item(item);
+        let old_entry = self.cursor_mut(index).store(stored_entry);
+        XEntry::into_item(old_entry)
     }
-}
-
-pub struct Cursor<'a, I: ItemEntry, M: XMark> {
-    xa: &'a XArray<I, M>,
-    xas: State<I, M>,
-}
 
-impl<'a, I: ItemEntry, M: XMark> Cursor<'a, I, M> {
-    pub fn current(&mut self) -> &'a XEntry {
-        let Self { xa, xas } = self;
-        xas.load(xa)
+    /// Removes the `XEntry` at the target index within the `XArray`,
+    /// and return the removed item if it was previously stored in target index.
+    pub fn remove(&mut self, index: u64) -> Option<I> {
+        let old_entry = self.cursor_mut(index).remove();
+        XEntry::into_item(old_entry)
     }
 
-    pub fn key(&mut self) -> u64 {
-        self.xas.index
+    /// Create an `Cursor` to perform read related operations on the `XArray`.
+    fn cursor<'a>(&'a self, index: u64) -> Cursor<'a, I> {
+        Cursor::new(self, index)
     }
-}
-
-pub struct CursorMut<'a, I: ItemEntry, M: XMark> {
-    xa: &'a mut XArray<I, M>,
-    xas: State<I, M>,
-}
 
-impl<'a, I: ItemEntry, M: XMark> CursorMut<'a, I, M> {
-    pub fn current(&'a mut self) -> &'a XEntry {
-        let Self { xa, xas } = self;
-        xas.load(xa)
-    }
-
-    pub fn store(&mut self, item: I) {
-        let Self { xa, xas } = self;
-        xas.store(xa, Some(OwnedEntry::from_item(item)));
-    }
-
-    pub fn remove(&mut self) {
-        let Self { xa, xas } = self;
-        xas.store(xa, None);
-    }
-
-    pub fn key(&mut self) -> u64 {
-        self.xas.index
+    /// Create an `CursorMut` to perform read and write operations on the `XArray`.
+    fn cursor_mut<'a>(&'a mut self, index: u64) -> CursorMut<'a, I> {
+        CursorMut::new(self, index)
     }
 }
 
-impl<I: ItemEntry, M: XMark> Drop for XArray<I, M> {
-    fn drop(&mut self) {
-        if self.head.is_node() {
-            OwnedEntry::<I, Node>::from_raw(self.head);
+impl<I: ItemEntry + Clone> Clone for XArray<I> {
+    /// Clone with cow mechanism.
+    fn clone(&self) -> Self {
+        let cloned_head = self.head.clone();
+        Self {
+            head: cloned_head,
+            _marker: PhantomData,
         }
     }
 }