Improve unit tests and Document.

README.md

@@ -25,29 +25,32 @@ This crate is developed in `no_std` environment, but std users can still use thi
 
 The following section covers how to interact with `XArray` including creating an `XArray`, using cursors, marking, cloning, and more.
 
+---
 ### Creating an `XArray`:
-- Users should declare the type of items (Arc<i32>) stored in the XArray and the lock (StdMutex) used inside the XArray. Note that `StdMutex` is an abstraction for `std::sync::Mutex`.
-- The type of stored item must implement `ItemEntry` trait and the used lock abstraction must be generated by the macro `abstract_lock_to!`. The real lock type that be abstracted should implement `ValidLock` trait.
-- We implement `ItemEntry` for `alloc::sync::Arc` and `alloc::sync::Box` by default, and abstract `std::sync::Mutex` and `std::sync::RwLock` as `StdMutex` and `StdRwLock` for std users, respectively
-
 ```rust
+// In std environment
 extern crate alloc;
 
 use alloc::sync::Arc;
-use xarray::{XArray, StdMutex};
+use xarray::XArray;
 
 // Create a new XArray instance
-let mut xarray: XArray<Arc<i32>, StdMutex> = XArray::new();
+let mut xarray: XArray<Arc<i32>> = XArray::new();
 ```
 
+- Users should declare the type of items (Arc<i32>) stored in the XArray, and the item type should implement `ItemEntry` trait. 
+- We implement `ItemEntry` for `alloc::sync::Arc` and `alloc::sync::Box` by default, hence std users can use them directly.
+
+
+
 ### Using Cursor
 ```rust
 extern crate alloc;
 
 use alloc::sync::Arc;
-use xarray::{XArray, StdMutex};
+use xarray::XArray;
 
-let mut xarray_arc: XArray<Arc<i32>, StdMutex> = XArray::new();
+let mut xarray_arc: XArray<Arc<i32>> = XArray::new();
 
 let mut cursor = xarray_arc.cursor_mut(0);
 // Store the Arc at the index range 0~10000.
@@ -64,11 +67,38 @@ for i in 0..10000 {
     cursor.next();
 }
 ```
+
+### Specify inner Locks
+Here is an example of declaring a SpinLock in your own project library as an inner lock for an xarray:
+```rust
+    use crate::{SpinLock, SpinLockGuard};
+
+    impl<T> MutexLock<T> for SpinLock<T> {
+        type Target<'a> = SpinLockGuard<'a, T>
+        where T: 'a;
+
+        fn new(inner: T) -> Self {
+            SpinLock::new(inner)
+        }
+
+        fn lock(&self) -> Self::Target<'_> {
+            self.lock().unwrap()
+        }
+    }
+
+    abstract_lock_to!(SpinLock, MySpinLock);
+
+    let mut xarray_arc: XArray<Arc<i32>, MySpinLock> = XArray::new();
+    
+```
+
+- Here `MySpinLock` is a HKT(Higher-Kind Type) abstraction for `crate::SpinLock`. 
+- The real lock type that be abstracted should implement `MutexLock` trait. 
+- This crate has abstracted `std::sync::Mutex` to `StdMutex` and set it as the default inner lock for std users.
+
 ### Using Marks
-- Items and the `XArray` can have up to three distinct marks by default, with each mark independently maintained.
-- Users need to use a struct to represent the marks that need to be used. For the situation where multiple marks are required, these marks are typically encapsulated within an enumeration class.
-- This struct for marks should implement `Into<XMark>` trait and be declared in the generics list of XArray.
 
+Here is an example of using marks for the stored pages in the XArray, where PageMark represents the states of each individual Page:
 ```rust
 extern crate alloc;
 
@@ -76,67 +106,64 @@ use alloc::sync::Arc;
 use xarray::{XArray, XMark, StdMutex};
 
 #[derive(Clone, Copy)]
-enum MarkDemo {
-    Mark0,
-    Mark1,
-    Mark2,
+
+enum PageMark {
+    DirtyPage 
+    ...
 }
 
-impl Into<XMark> for MarkDemo {
-    fn into(self) -> XMark {
-        match self {
-            MarkDemo::Mark0 => XMark::Mark0,
-            MarkDemo::Mark1 => XMark::Mark1,
-            MarkDemo::Mark2 => XMark::Mark2,
+impl From<PageState> for XMark {
+    fn from(mark: PageState) -> Self {
+        match mark {
+            PageState::DirtyPage => Self::Mark0,
+            ...
         }
     }
 }
 
-let mut xarray_arc: XArray<Arc<i32>, StdMutex, MarkDemo> = XArray::new();
-// Mark the xarray with Mark1.
-xarray_arc.set_mark(MarkDemo::Mark0);
-assert!(xarray_arc.is_marked(MarkDemo::Mark0));
-
-let mut cursor = xarray_arc.cursor_mut(1000);
-let value = Arc::new(i * 2);
-cursor.store(value);
+let mut pages: XArray<Page, StdMutex, PageState> = XArray::new();
 
-// Mark the item with Mark1.
-cursor.set_mark(MarkDemo::Mark1).unwrap();
-assert!(cursor.is_marked(MarkDemo::Mark1));
+let mut cursor = pages.cursor_mut(1000);
+cursor.store(Page::alloc_zero());
+// Mark the Page as DirtyPage.
+cursor.set_mark(PageState::DirtyPage).unwrap();
+assert!(cursor.is_marked(PageState::DirtyPage));
 ```
+- Items and the `XArray` can have up to three distinct marks by default, with each mark independently maintained.
+- Users need to use a struct to represent the marks that need to be used. For the situation where multiple marks are required, these marks are typically encapsulated within an enumeration class.
+- If users want to use a struct `M` for marks, they should implement `From<M>` trait for `XMark` and declare `M` in the generics list of XArray.
 
 ### Copy-On-Write (COW) Clone
 ```rust
 use std::sync::Arc;
-use xarray::{XArray, StdMutex};
+use xarray::{XArray};
 
-let mut xarray: XArray<Arc<i32>, StdMutex> = XArray::new();
+let mut xarray: XArray<Arc<i32>> = XArray::new();
 
 // Store values
 let value = Arc::new(10);
-xarray.store(333, value.clone());
-assert_eq!(*xarray.load(333).unwrap().as_ref(), 10);
+xarray.store(1, value.clone());
+assert_eq!(*xarray.load(1).unwrap().as_ref(), 10);
 
 // Clone the XArray
 let mut xarray_clone = xarray.clone();
-assert_eq!(*xarray_clone.load(333).unwrap().as_ref(), 10);
+assert_eq!(*xarray_clone.load(1).unwrap().as_ref(), 10);
 
 // Store a new value in the clone
 let new_value = Arc::new(100);
-xarray_clone.store(333, new_value);
+xarray_clone.store(1, new_value);
 
 // The original XArray is unaffected by changes in the clone
-assert_eq!(*xarray.load(333).unwrap().as_ref(), 10);
-assert_eq!(*xarray_clone.load(333).unwrap().as_ref(), 100);
+assert_eq!(*xarray.load(1).unwrap().as_ref(), 10);
+assert_eq!(*xarray_clone.load(1).unwrap().as_ref(), 100);
 ```
 
 ### Iteration
 ```rust
 use std::sync::Arc;
-use xarray::{XArray, StdMutex};
+use xarray::XArray;
 
-let mut xarray: XArray<Arc<i32>, StdMutex> = XArray::new();
+let mut xarray: XArray<Arc<i32>> = XArray::new();
 
 // Store item to even index in the range 100~200.
 for i in 100..200 {

src/cow.rs

@@ -1,6 +1,6 @@
 use crate::entry::{ItemEntry, XEntry};
 use crate::lock::XLock;
-use crate::node::deep_clone_node_entry;
+use crate::node::deep_copy_node_entry;
 
 /// The COW trait provides the capability for Copy-On-Write (COW) behavior to XEntries with Clone ability.
 pub(super) trait Cow<I: ItemEntry, L: XLock> {
@@ -19,7 +19,7 @@ impl<I: ItemEntry, L: XLock> Cow<I, L> for XEntry<I, L> {
 impl<I: ItemEntry + Clone, L: XLock> Cow<I, L> for XEntry<I, L> {
     fn copy_if_shared(&self) -> Option<XEntry<I, L>> {
         if self.is_node() && self.node_strong_count().unwrap() > 1 {
-            let new_entry = deep_clone_node_entry(self);
+            let new_entry = deep_copy_node_entry(self);
             Some(new_entry)
         } else {
             None

src/cursor.rs

@@ -1,3 +1,6 @@
+use core::marker::PhantomData;
+use core::ops::Deref;
+
 use smallvec::SmallVec;
 
 use crate::entry::{ItemEntry, XEntry};
@@ -5,8 +8,6 @@ use crate::lock::XLock;
 use crate::mark::XMark;
 use crate::node::{Height, ReadOnly, ReadWrite, XNode};
 use crate::xarray::{XArray, MAX_HEIGHT, SLOT_SIZE};
-use core::marker::PhantomData;
-use core::ops::Deref;
 
 /// CursorState represents the current state of the cursor. Currently, there are two possible states:
 /// 1. inactive: the state where the cursor is not positioned on any node.

src/lib.rs

@@ -10,7 +10,7 @@ extern crate alloc;
 
 pub use cursor::{Cursor, CursorMut};
 pub use entry::ItemEntry;
-pub use lock::{ValidLock, XLock};
+pub use lock::{MutexLock, XLock};
 pub use mark::XMark;
 pub use range::Range;
 pub use xarray::XArray;

src/lock.rs

@@ -1,8 +1,12 @@
 use core::ops::{Deref, DerefMut};
 
-/// ValidLock is a trait that needs to be implemented for locks used internally within XArray.
+/// MutexLock is a trait that needs to be implemented for locks used internally within XArray.
 /// It abstracts the functionalities of the necessary locks inside.
-pub trait ValidLock<T>: Sized {
+///
+/// Since XArray features a copy-on-write cloning capability, its internal nodes may be subject
+/// to concurrent access in a multi-threaded environment. Therefore,
+/// the mutable data within XNode needs to be managed using a mutual exclusion lock.
+pub trait MutexLock<T>: Sized {
     type Target<'a>: Deref<Target = T> + DerefMut<Target = T>
     where
         Self: 'a;
@@ -12,26 +16,26 @@ pub trait ValidLock<T>: Sized {
     fn lock(&self) -> Self::Target<'_>;
 }
 
-/// XLock represents a HKT (Higher-Kinded Type) abstraction of ValidLock used within XArray,
+/// XLock represents a HKT (Higher-Kind Type) abstraction of MutexLock used within XArray,
 /// leveraging Rust's GAT (Generic Associated Types) to empower an HKT.
 ///
 /// This trait is typically auto-implemented via the abstract_lock_to! macro. For example, for a lock type Mutex<T>,
-/// using `abstract_lock_to!(Mutex, XMutex);` yields the corresponding higher-kinded type XMutex,
+/// using `abstract_lock_to!(Mutex, XMutex);` yields the corresponding higher-kind type XMutex,
 /// which is automatically implemented with the XLock trait inside the macro. This allows XMutex to serve any type T,
 /// obtaining the corresponding Mutex<T> by using `XMutex::Lock<T>`.
 pub trait XLock {
-    type Lock<T>: ValidLock<T>;
+    type Lock<T>: MutexLock<T>;
 
     fn new<T>(inner: T) -> Self::Lock<T> {
         Self::Lock::<T>::new(inner)
     }
 }
 
-#[macro_export]
-/// Abstract a lock type that implements `ValidLock` to its HKT (Higher-Kinded Type) struct.
+/// Abstract a lock type that implements `MutexLock` to its HKT (Higher-Kinded Type) struct.
 /// The first parameter is the source type name and the second parameter is the HKT type name.
 /// This HKT type will implement `XLock` trait automatically and can be used as a generic parameter
 /// for `XArray`.
+#[macro_export]
 macro_rules! abstract_lock_to {
     ($lock_type:ident, $name:ident) => {
         pub struct $name;
@@ -49,7 +53,7 @@ pub mod std_specific {
     use crate::*;
     use std::sync::{Mutex, MutexGuard};
 
-    impl<T> ValidLock<T> for Mutex<T> {
+    impl<T> MutexLock<T> for Mutex<T> {
         type Target<'a> = MutexGuard<'a, T>
         where T: 'a;
 

src/node.rs

@@ -6,7 +6,7 @@ use core::{
 
 use crate::cow::Cow;
 use crate::entry::{ItemEntry, XEntry};
-use crate::lock::{ValidLock, XLock};
+use crate::lock::{MutexLock, XLock};
 use crate::mark::Mark;
 use crate::xarray::{BITS_PER_LAYER, SLOT_MASK, SLOT_SIZE};
 
@@ -232,7 +232,7 @@ impl<I: ItemEntry, L: XLock> XNodeInner<I, L> {
     }
 }
 
-pub(super) fn deep_clone_node_entry<I: ItemEntry + Clone, L: XLock>(
+pub(super) fn deep_copy_node_entry<I: ItemEntry + Clone, L: XLock>(
     entry: &XEntry<I, L>,
 ) -> XEntry<I, L> {
     debug_assert!(entry.is_node());

src/range.rs

@@ -12,12 +12,13 @@ where
     M: Into<XMark>,
 {
     cursor: Cursor<'a, I, L, M>,
+    start: u64,
     end: u64,
 }
 
 impl<'a, I: ItemEntry, L: XLock, M: Into<XMark>> Range<'a, I, L, M> {
-    pub(super) fn new(cursor: Cursor<'a, I, L, M>, end: u64) -> Self {
-        Range { cursor, end }
+    pub(super) fn new(cursor: Cursor<'a, I, L, M>, start: u64, end: u64) -> Self {
+        Range { cursor, start, end }
     }
 }
 

src/test.rs

@@ -5,123 +5,203 @@ use std::sync::Arc;
 extern crate test;
 use test::Bencher;
 
-#[derive(Clone, Copy)]
-enum MarkDemo {
-    Mark0,
-    Mark1,
-    Mark2,
+fn init_continuous_with_arc<M: Into<XMark>>(
+    xarray: &mut XArray<Arc<i32>, StdMutex, M>,
+    item_num: i32,
+) {
+    for i in 0..item_num {
+        let value = Arc::new(i);
+        xarray.store(i as u64, value);
+    }
 }
 
-impl Into<XMark> for MarkDemo {
-    fn into(self) -> XMark {
-        match self {
-            Self::Mark0 => XMark::Mark0,
-            Self::Mark1 => XMark::Mark1,
-            Self::Mark2 => XMark::Mark2,
+fn init_sparse_with_arc<M: Into<XMark>>(xarray: &mut XArray<Arc<i32>, StdMutex, M>, item_num: i32) {
+    for i in 0..2 * item_num {
+        if i % 2 == 0 {
+            let value = Arc::new(i);
+            xarray.store(i as u64, value);
         }
     }
 }
 
 #[test]
-fn test_simple_store() {
-    let mut xarray_arc: XArray<Arc<i32>, StdMutex> = XArray::new();
+fn test_store_continuous() {
+    let mut xarray_arc: XArray<Arc<i32>> = XArray::new();
+    init_continuous_with_arc(&mut xarray_arc, 10000);
     for i in 0..10000 {
-        let value = Arc::new(i * 2);
-        xarray_arc.store((i * 3) as u64, value);
+        let value = xarray_arc.load(i as u64).unwrap();
+        assert_eq!(*value.as_ref(), i);
     }
+}
+
+#[test]
+fn test_store_sparse() {
+    let mut xarray_arc: XArray<Arc<i32>> = XArray::new();
+    init_sparse_with_arc(&mut xarray_arc, 10000);
     for i in 0..10000 {
-        let value = xarray_arc.load((i * 3) as u64).unwrap();
-        assert!(*value.as_ref() == i * 2)
+        if i % 2 == 0 {
+            let value = xarray_arc.load(i as u64).unwrap();
+            assert_eq!(*value.as_ref(), i);
+        }
     }
 }
 
 #[test]
-fn test_overwrite_store() {
-    let mut xarray_arc: XArray<Arc<i32>, StdMutex> = XArray::new();
-
+fn test_store_overwrite() {
+    let mut xarray_arc: XArray<Arc<i32>> = XArray::new();
+    init_continuous_with_arc(&mut xarray_arc, 10000);
+    // Overwrite 20 at index 10.
     let value = Arc::new(20);
     xarray_arc.store(10, value);
     let v = xarray_arc.load(10).unwrap();
-    assert!(*v.as_ref() == 20);
-
+    assert_eq!(*v.as_ref(), 20);
+    // Overwrite 40 at index 10.
     let value = Arc::new(40);
     xarray_arc.store(10, value);
     let v = xarray_arc.load(10).unwrap();
-    assert!(*v.as_ref() == 40);
+    assert_eq!(*v.as_ref(), 40);
 }
 
 #[test]
 fn test_remove() {
-    let mut xarray_arc: XArray<Arc<i32>, StdMutex> = XArray::new();
-    assert!(xarray_arc.remove(66).is_none());
-    for i in 0..10000 {
-        let value = Arc::new(i * 2);
-        xarray_arc.store(i as u64, value);
-    }
+    let mut xarray_arc: XArray<Arc<i32>> = XArray::new();
+    assert!(xarray_arc.remove(100).is_none());
+    init_continuous_with_arc(&mut xarray_arc, 10000);
+
     for i in 0..10000 {
-        assert!(xarray_arc.remove(i as u64).is_some());
+        assert_eq!(*xarray_arc.remove(i as u64).unwrap().as_ref(), i);
         let value = xarray_arc.load(i as u64);
-        assert!(value == None);
+        assert_eq!(value, None);
         assert!(xarray_arc.remove(i as u64).is_none());
     }
 }
 
 #[test]
-fn test_mark() {
-    let mut xarray_arc: XArray<Arc<i32>, StdMutex, MarkDemo> = XArray::new();
-    for i in 1..10000 {
-        let value = Arc::new(i * 2);
-        xarray_arc.store(i as u64, value);
+fn test_cursor_load() {
+    let mut xarray_arc: XArray<Arc<i32>> = XArray::new();
+    init_continuous_with_arc(&mut xarray_arc, 10000);
+
+    let mut cursor = xarray_arc.cursor(0);
+
+    for i in 0..10000 {
+        let value = cursor.load().unwrap();
+        assert_eq!(*value.as_ref(), i);
+        cursor.next();
     }
-    let mut cursor = xarray_arc.cursor_mut(1000);
-    cursor.set_mark(MarkDemo::Mark0).unwrap();
-    cursor.set_mark(MarkDemo::Mark1).unwrap();
-    cursor.reset_to(2000);
-    cursor.set_mark(MarkDemo::Mark1).unwrap();
+
     cursor.reset_to(20000);
-    assert!(Err(()) == cursor.set_mark(MarkDemo::Mark1));
-    assert!(None == cursor.load());
+    assert!(cursor.load().is_none());
+}
+
+#[test]
+fn test_cursor_store_continuous() {
+    let mut xarray_arc: XArray<Arc<i32>> = XArray::new();
+    let mut cursor = xarray_arc.cursor_mut(0);
+
+    for i in 0..10000 {
+        let value = Arc::new(i);
+        cursor.store(value);
+        cursor.next();
+    }
     drop(cursor);
 
-    let mut cursor = xarray_arc.cursor(1000);
-    let value1 = cursor.load().unwrap();
-    let value1_mark0 = cursor.is_marked(MarkDemo::Mark0);
-    let value1_mark1 = cursor.is_marked(MarkDemo::Mark1);
+    for i in 0..10000 {
+        let value = xarray_arc.load(i as u64).unwrap();
+        assert_eq!(*value.as_ref(), i);
+    }
+}
+
+#[test]
+fn test_cursor_store_sparse() {
+    let mut xarray_arc: XArray<Arc<i32>> = XArray::new();
+    let mut cursor = xarray_arc.cursor_mut(0);
+
+    for i in 0..10000 {
+        if i % 2 == 0 {
+            let value = Arc::new(i);
+            cursor.store(value);
+        }
+        cursor.next();
+    }
+    drop(cursor);
+
+    for i in 0..10000 {
+        if i % 2 == 0 {
+            let value = xarray_arc.load(i as u64).unwrap();
+            assert_eq!(*value.as_ref(), i);
+        }
+    }
+}
+
+#[test]
+fn test_set_mark() {
+    let mut xarray_arc: XArray<Arc<i32>, StdMutex, XMark> = XArray::new();
+    init_continuous_with_arc(&mut xarray_arc, 10000);
+
+    let mut cursor = xarray_arc.cursor_mut(1000);
+    cursor.set_mark(XMark::Mark0).unwrap();
+    cursor.set_mark(XMark::Mark1).unwrap();
+    cursor.reset_to(2000);
+    cursor.set_mark(XMark::Mark1).unwrap();
+
+    cursor.reset_to(1000);
+    let value1_mark0 = cursor.is_marked(XMark::Mark0);
+    let value1_mark1 = cursor.is_marked(XMark::Mark1);
 
     cursor.reset_to(2000);
-    let value2 = cursor.load().unwrap();
-    let value2_mark0 = cursor.is_marked(MarkDemo::Mark0);
-    let value2_mark1 = cursor.is_marked(MarkDemo::Mark1);
+    let value2_mark0 = cursor.is_marked(XMark::Mark0);
+    let value2_mark1 = cursor.is_marked(XMark::Mark1);
 
     cursor.reset_to(3000);
-    let value3 = cursor.load().unwrap();
-    let value3_mark1 = cursor.is_marked(MarkDemo::Mark1);
+    let value3_mark1 = cursor.is_marked(XMark::Mark1);
 
-    assert!(*value1.as_ref() == 2000);
-    assert!(*value2.as_ref() == 4000);
-    assert!(*value3.as_ref() == 6000);
     assert!(value1_mark0 == true);
     assert!(value1_mark1 == true);
     assert!(value2_mark0 == false);
     assert!(value2_mark1 == true);
     assert!(value3_mark1 == false);
-    drop(cursor);
+}
+
+#[test]
+fn test_unset_mark() {
+    let mut xarray_arc: XArray<Arc<i32>, StdMutex, XMark> = XArray::new();
+    init_continuous_with_arc(&mut xarray_arc, 10000);
 
     let mut cursor = xarray_arc.cursor_mut(1000);
-    cursor.unset_mark(MarkDemo::Mark0).unwrap();
-    cursor.unset_mark(MarkDemo::Mark2).unwrap();
-    drop(cursor);
+    cursor.set_mark(XMark::Mark0).unwrap();
+    cursor.set_mark(XMark::Mark1).unwrap();
 
-    let cursor = xarray_arc.cursor(1000);
-    let value1_mark0 = cursor.is_marked(MarkDemo::Mark0);
-    let value1_mark2 = cursor.is_marked(MarkDemo::Mark2);
+    cursor.unset_mark(XMark::Mark0).unwrap();
+    cursor.unset_mark(XMark::Mark2).unwrap();
+
+    let value1_mark0 = cursor.is_marked(XMark::Mark0);
+    let value1_mark2 = cursor.is_marked(XMark::Mark2);
     assert!(value1_mark0 == false);
     assert!(value1_mark2 == false);
-    drop(cursor);
+}
 
-    xarray_arc.unset_mark_all(MarkDemo::Mark1);
-    let value2_mark1 = xarray_arc.cursor(2000).is_marked(MarkDemo::Mark1);
-    assert!(value2_mark1 == false);
+#[test]
+fn test_mark_overflow() {
+    let mut xarray_arc: XArray<Arc<i32>, StdMutex, XMark> = XArray::new();
+    init_continuous_with_arc(&mut xarray_arc, 10000);
+
+    let mut cursor = xarray_arc.cursor_mut(20000);
+    assert!(Err(()) == cursor.set_mark(XMark::Mark1));
+    assert!(false == cursor.is_marked(XMark::Mark1));
+}
+
+#[test]
+fn test_unset_mark_all() {
+    let mut xarray_arc: XArray<Arc<i32>, StdMutex, XMark> = XArray::new();
+    init_continuous_with_arc(&mut xarray_arc, 10000);
+    xarray_arc.cursor_mut(2000).set_mark(XMark::Mark1);
+    xarray_arc.cursor_mut(2000).set_mark(XMark::Mark2);
+    xarray_arc.cursor_mut(200).set_mark(XMark::Mark1);
+    xarray_arc.unset_mark_all(XMark::Mark1);
+
+    assert_eq!(xarray_arc.cursor(2000).is_marked(XMark::Mark1), false);
+    assert_eq!(xarray_arc.cursor(2000).is_marked(XMark::Mark2), true);
+    assert_eq!(xarray_arc.cursor(200).is_marked(XMark::Mark1), false);
 }
 
 #[test]
@@ -147,13 +227,16 @@ fn test_cow() {
             Self { raw }
         }
     }
-    let mut xarray_arc: XArray<Arc<Wrapper>, StdMutex> = XArray::new();
+    // Init xarray_arc.
+    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);
     }
+    // Clone the xarray_arc.
     let mut xarray_clone = xarray_arc.clone();
 
+    // Store different items in xarray_arc and xarray_clone respectively.
     for i in 1..10000 {
         if i % 2 == 0 {
             let value = Arc::new(Wrapper::new(i * 6));
@@ -163,7 +246,7 @@ fn test_cow() {
             xarray_clone.store(i as u64, value);
         }
     }
-
+    // Determine whether they do not affect each other
     for i in 1..10000 {
         let value_origin = xarray_arc.load(i).unwrap();
         let value_clone = xarray_clone.load(i).unwrap();
@@ -177,25 +260,26 @@ fn test_cow() {
     }
     drop(xarray_arc);
     drop(xarray_clone);
+    // Check drop times.
     assert!(INIT_TIMES.load(Ordering::Relaxed) == DROP_TIMES.load(Ordering::Relaxed));
 }
 
 #[test]
 fn test_cow_after_cow() {
-    let mut xarray_arc: XArray<Arc<u64>, StdMutex> = XArray::new();
+    let mut xarray_arc: XArray<Arc<u64>> = XArray::new();
     for i in 1..10000 {
         let value = Arc::new(i * 2);
         xarray_arc.store(i as u64, value);
     }
     // First COW.
     let mut xarray_cow1 = xarray_arc.clone();
-    for i in 5000..6000 {
+    for i in 5000..7000 {
         let value = Arc::new(i * 3);
         xarray_cow1.store(i as u64, value);
     }
     // Second COW.
     let mut xarray_cow2 = xarray_arc.clone();
-    for i in 5500..7000 {
+    for i in 6000..8000 {
         let value = Arc::new(i * 4);
         xarray_cow2.store(i as u64, value);
     }
@@ -203,20 +287,20 @@ fn test_cow_after_cow() {
     let xarray_cow1_cow = xarray_cow1.clone();
     let xarray_cow2_cow = xarray_cow2.clone();
 
-    assert!(*xarray_cow1_cow.load(2341).unwrap().as_ref() == 2341 * 2);
+    assert!(*xarray_cow1_cow.load(2000).unwrap().as_ref() == 2000 * 2);
     assert!(*xarray_cow1_cow.load(5100).unwrap().as_ref() == 5100 * 3);
-    assert!(*xarray_cow1_cow.load(5677).unwrap().as_ref() == 5677 * 3);
-    assert!(*xarray_cow1_cow.load(6315).unwrap().as_ref() == 6315 * 2);
+    assert!(*xarray_cow1_cow.load(6100).unwrap().as_ref() == 6100 * 3);
+    assert!(*xarray_cow1_cow.load(7100).unwrap().as_ref() == 7100 * 2);
 
-    assert!(*xarray_cow2_cow.load(2341).unwrap().as_ref() == 2341 * 2);
+    assert!(*xarray_cow2_cow.load(2000).unwrap().as_ref() == 2000 * 2);
     assert!(*xarray_cow2_cow.load(5100).unwrap().as_ref() == 5100 * 2);
-    assert!(*xarray_cow2_cow.load(5677).unwrap().as_ref() == 5677 * 4);
-    assert!(*xarray_cow2_cow.load(6315).unwrap().as_ref() == 6315 * 4);
+    assert!(*xarray_cow2_cow.load(6100).unwrap().as_ref() == 6100 * 4);
+    assert!(*xarray_cow2_cow.load(7100).unwrap().as_ref() == 7100 * 4);
 }
 
 #[test]
 fn test_cow_mark() {
-    let mut xarray_arc: XArray<Arc<i32>, StdMutex, MarkDemo> = XArray::new();
+    let mut xarray_arc: XArray<Arc<i32>, StdMutex, XMark> = XArray::new();
     for i in 1..10000 {
         let value = Arc::new(i * 2);
         xarray_arc.store(i as u64, value);
@@ -224,25 +308,25 @@ fn test_cow_mark() {
     let mut xarray_clone = xarray_arc.clone();
     let mut cursor_arc = xarray_arc.cursor_mut(1000);
     let mut cursor_clone = xarray_clone.cursor_mut(1000);
-    cursor_arc.set_mark(MarkDemo::Mark0).unwrap();
+    cursor_arc.set_mark(XMark::Mark0).unwrap();
     cursor_arc.reset_to(2000);
-    cursor_arc.set_mark(MarkDemo::Mark0).unwrap();
+    cursor_arc.set_mark(XMark::Mark0).unwrap();
     cursor_arc.reset_to(3000);
-    cursor_arc.set_mark(MarkDemo::Mark0).unwrap();
+    cursor_arc.set_mark(XMark::Mark0).unwrap();
 
-    cursor_clone.set_mark(MarkDemo::Mark1).unwrap();
+    cursor_clone.set_mark(XMark::Mark1).unwrap();
     drop(cursor_arc);
     drop(cursor_clone);
 
-    let mark0_1000_arc = xarray_arc.cursor(1000).is_marked(MarkDemo::Mark0);
-    let mark0_2000_arc = xarray_arc.cursor(2000).is_marked(MarkDemo::Mark0);
-    let mark1_1000_arc = xarray_arc.cursor(1000).is_marked(MarkDemo::Mark1);
-    let mark0_3000_arc = xarray_arc.cursor(3000).is_marked(MarkDemo::Mark0);
+    let mark0_1000_arc = xarray_arc.cursor(1000).is_marked(XMark::Mark0);
+    let mark0_2000_arc = xarray_arc.cursor(2000).is_marked(XMark::Mark0);
+    let mark1_1000_arc = xarray_arc.cursor(1000).is_marked(XMark::Mark1);
+    let mark0_3000_arc = xarray_arc.cursor(3000).is_marked(XMark::Mark0);
 
-    let mark0_1000_clone = xarray_clone.cursor(1000).is_marked(MarkDemo::Mark0);
-    let mark0_2000_clone = xarray_clone.cursor(2000).is_marked(MarkDemo::Mark0);
-    let mark1_1000_clone = xarray_clone.cursor(1000).is_marked(MarkDemo::Mark1);
-    let mark0_3000_clone = xarray_clone.cursor(3000).is_marked(MarkDemo::Mark0);
+    let mark0_1000_clone = xarray_clone.cursor(1000).is_marked(XMark::Mark0);
+    let mark0_2000_clone = xarray_clone.cursor(2000).is_marked(XMark::Mark0);
+    let mark1_1000_clone = xarray_clone.cursor(1000).is_marked(XMark::Mark1);
+    let mark0_3000_clone = xarray_clone.cursor(3000).is_marked(XMark::Mark0);
 
     assert!(mark0_1000_arc == true);
     assert!(mark0_2000_arc == true);
@@ -255,33 +339,8 @@ fn test_cow_mark() {
 }
 
 #[test]
-fn test_next() {
-    let mut xarray_arc: XArray<Arc<i32>, StdMutex> = XArray::new();
-    for i in 1..10000 {
-        let value = Arc::new(i * 2);
-        xarray_arc.store(i as u64, value);
-    }
-    let mut cursor = xarray_arc.cursor_mut(0);
-    for i in 1..10000 {
-        cursor.next();
-        let value = cursor.load().unwrap();
-        assert!(*value.as_ref() == i * 2)
-    }
-    for i in 0..10000 {
-        cursor.next();
-        let value = Arc::new((10000 + i) * 2);
-        cursor.store(value);
-    }
-    drop(cursor);
-    for i in 10000..20000 {
-        let value = xarray_arc.load(i as u64).unwrap();
-        assert!(*value.as_ref() == i * 2)
-    }
-}
-
-#[test]
-fn test_cow_next() {
-    let mut xarray_arc: XArray<Arc<u64>, StdMutex> = XArray::new();
+fn test_cow_cursor() {
+    let mut xarray_arc: XArray<Arc<u64>> = XArray::new();
     for i in 1..10000 {
         let value = Arc::new(i * 2);
         xarray_arc.store(i as u64, value);
@@ -290,14 +349,14 @@ fn test_cow_next() {
 
     let mut cursor_clone = xarray_clone.cursor_mut(1);
     let mut cursor_arc = xarray_arc.cursor_mut(1);
-    // Use next to read xarray_clone;
+    // Use cursor to read xarray_clone;
     while cursor_clone.index() < 10000 {
         let item = cursor_clone.load().unwrap();
         assert!(*item.as_ref() == cursor_clone.index() * 2);
         cursor_clone.next();
     }
 
-    // Use next to write xarray_clone;
+    // Use cursor to write xarray_clone;
     cursor_clone.reset_to(1);
     while cursor_clone.index() < 10000 {
         let value = Arc::new(cursor_clone.index());
@@ -306,14 +365,14 @@ fn test_cow_next() {
         cursor_clone.next();
     }
 
-    // Use next to read xarray_arc;
+    // Use cursor to read xarray_arc;
     while cursor_arc.index() < 10000 {
         let item = cursor_arc.load().unwrap();
         assert!(*item.as_ref() == cursor_arc.index() * 2);
         cursor_arc.next();
     }
 
-    // Use next to write xarray_arc;
+    // Use cursor to write xarray_arc;
     cursor_arc.reset_to(1);
     while cursor_arc.index() < 10000 {
         let value = Arc::new(cursor_arc.index() * 3);
@@ -322,7 +381,7 @@ fn test_cow_next() {
         cursor_arc.next();
     }
 
-    // Use next to read xarray_arc and xarray_clone;
+    // Use cursor to read xarray_arc and xarray_clone;
     cursor_arc.reset_to(1);
     cursor_clone.reset_to(1);
     while cursor_arc.index() < 10000 {
@@ -337,7 +396,7 @@ fn test_cow_next() {
 
 #[test]
 fn test_range() {
-    let mut xarray_arc: XArray<Arc<i32>, StdMutex> = XArray::new();
+    let mut xarray_arc: XArray<Arc<i32>> = XArray::new();
     for i in 0..10000 {
         let value = Arc::new(i * 2);
         xarray_arc.store((i * 2) as u64, value);
@@ -352,6 +411,16 @@ fn test_range() {
 }
 
 #[bench]
-fn benchmark_next(b: &mut Bencher) {
-    b.iter(|| test_next());
+fn benchmark_cursor_load(b: &mut Bencher) {
+    b.iter(|| test_cursor_load());
+}
+
+#[bench]
+fn benchmark_cursor_store_continuous(b: &mut Bencher) {
+    b.iter(|| test_cursor_store_continuous());
+}
+
+#[bench]
+fn benchmark_cursor_store_sparse(b: &mut Bencher) {
+    b.iter(|| test_cursor_store_sparse());
 }

src/xarray.rs

@@ -7,6 +7,8 @@ use crate::entry::{ItemEntry, XEntry};
 use crate::lock::XLock;
 use crate::mark::{NoneMark, XMark};
 use crate::range::Range;
+#[cfg(feature = "std")]
+use crate::StdMutex;
 
 pub(super) const BITS_PER_LAYER: usize = 6;
 pub(super) const SLOT_SIZE: usize = 1 << BITS_PER_LAYER;
@@ -34,7 +36,7 @@ pub(super) const MAX_HEIGHT: usize = 64 / BITS_PER_LAYER + 1;
 ///
 /// **Marking:** `XArray` enables marking of individual items or the `XArray` itself for user convenience.
 /// Items and the `XArray` can have up to three distinct marks by default, with each mark independently maintained.
-/// Users can use self-defined types as marks by implementing the `Into<XMark>` trait for them.
+/// Users can use self-defined types as marks by implementing the `From<Type>` trait for XMark.
 /// Marking is also applicable to internal nodes, indicating marked descendant nodes,
 /// though such marking is not transparent to users.
 ///
@@ -45,24 +47,28 @@ pub(super) const MAX_HEIGHT: usize = 64 / BITS_PER_LAYER + 1;
 /// use std::sync::{Mutex, MutexGuard};
 /// use xarray::*;
 ///
-/// let mut xarray_arc: XArray<Arc<i32>, StdMutex> = XArray::new();
+/// 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);
+/// xarray_arc.store(10, value);
+/// assert!(*xarray_arc.load(10).unwrap().as_ref() == 10);
 ///
 /// let mut xarray_clone = xarray_arc.clone();
-/// assert!(*xarray_clone.load(333).unwrap().as_ref() == 10);
+/// assert!(*xarray_clone.load(10).unwrap().as_ref() == 10);
 /// let value = Arc::new(100);
-/// xarray_clone.store(333, value);
+/// xarray_clone.store(10, value);
 ///
-/// assert!(*xarray_arc.load(333).unwrap().as_ref() == 10);
-/// assert!(*xarray_clone.load(333).unwrap().as_ref() == 100);
+/// assert!(*xarray_arc.load(10).unwrap().as_ref() == 10);
+/// assert!(*xarray_clone.load(10).unwrap().as_ref() == 100);
 /// ```
 ///
 /// 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, L, M = NoneMark>
-where
+pub struct XArray<
+    I,
+    #[cfg(feature = "std")] L = StdMutex,
+    #[cfg(not(feature = "std"))] L,
+    M = NoneMark,
+> where
     I: ItemEntry,
     L: XLock,
     M: Into<XMark>,
@@ -188,7 +194,7 @@ impl<I: ItemEntry, L: XLock, M: Into<XMark>> XArray<I, L, M> {
     /// in `XArray`.
     pub fn range(&self, range: core::ops::Range<u64>) -> Range<'_, I, L, M> {
         let cursor = Cursor::new(self, range.start);
-        Range::new(cursor, range.end)
+        Range::new(cursor, range.start, range.end)
     }
 }