A minimal runnable version of XArray.

.gitignore

@@ -0,0 +1 @@
+/target

Cargo.lock

@@ -0,0 +1,7 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 3
+
+[[package]]
+name = "xarray"
+version = "0.1.0"

Cargo.toml

@@ -0,0 +1,8 @@
+[package]
+name = "xarray"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]

src/entry.rs

@@ -0,0 +1,331 @@
+use std::{
+    marker::PhantomData,
+    mem::{self, ManuallyDrop, MaybeUninit},
+    sync::{Arc, RwLock},
+};
+
+use crate::*;
+
+/// 用来抽象用户将要存入XArray的指针类型
+/// 可以为诸如Arc、Box等实现，用户也可以自己为自定义的指针类型实现该trait
+pub trait PointerItem {
+    /// 将原有的指针类型转化为一个裸指针
+    ///
+    /// # Safety
+    /// 用户需要确保该裸指针与原指针在内存布局上一致
+    /// 也就是原指针大小跟裸指针大小一致，且指向的位置一致
+    /// 同时需要确保原指针是aligned to 4的，因为XArray中的entry后两位要用于entry类型判断。
+    unsafe fn into_raw(self) -> *const u8;
+
+    /// 将一个裸指针转化为原指针
+    ///
+    /// # Safety
+    /// 裸指针必须是通过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。
+    fn into_raw(self) -> usize;
+
+    /// 由usize恢复原类型，恢复所有权
+    ///
+    /// # Safety
+    /// 传入的raw必须是由into_raw生成的
+    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;
+
+    fn into_raw(self) -> usize {
+        let raw_ptr = unsafe { I::into_raw(self) };
+        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)
+    }
+}
+
+impl ItemEntry for usize {
+    type Target<'a> = usize;
+
+    fn into_raw(self) -> usize {
+        debug_assert!(self <= usize::MAX >> 1);
+        (self << 1) | 1
+    }
+
+    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)
+    }
+}
+
+pub(crate) struct Item {}
+
+pub(crate) struct Node {}
+
+/// XArray中有所有权的Entry，只有两种Type，Item以及Node，分别对应ItemEntry以及指向Node的Entry
+/// 指向Node的Entry目前有统一的结构类型，也就是Arc<RwLock<XNode<I>>>。
+#[derive(Eq)]
+#[repr(transparent)]
+pub struct OwnedEntry<I: ItemEntry, Type> {
+    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
+    }
+}
+
+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> {
+    fn drop(&mut self) {
+        if self.is_item() {
+            unsafe {
+                I::from_raw(self.raw);
+            }
+        }
+        if self.is_node() {
+            unsafe {
+                Arc::from_raw((self.raw - 2) as *const RwLock<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,
+            })
+        } else {
+            None
+        }
+    }
+
+    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
+        }
+    }
+
+    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)
+    }
+
+    pub(crate) fn as_node(&self) -> &RwLock<XNode<I>> {
+        unsafe {
+            let node_ref = &*((self.raw - 2) as *const RwLock<XNode<I>>);
+            node_ref
+        }
+    }
+}
+
+impl<I: ItemEntry, Type> OwnedEntry<I, Type> {
+    pub(crate) const fn new(raw: usize) -> Self {
+        Self {
+            raw,
+            _marker: core::marker::PhantomData,
+        }
+    }
+
+    pub(crate) fn is_null(&self) -> bool {
+        self.raw == 0
+    }
+
+    pub(crate) fn is_internal(&self) -> bool {
+        self.raw & 3 == 2
+    }
+
+    pub(crate) fn is_item(&self) -> bool {
+        !self.is_null() && !self.is_internal()
+    }
+
+    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 }
+    }
+
+    pub(crate) fn is_null(&self) -> bool {
+        self.raw == 0
+    }
+
+    pub(crate) fn is_internal(&self) -> bool {
+        self.raw & 3 == 2
+    }
+
+    pub(crate) fn is_item(&self) -> bool {
+        !self.is_null() && !self.is_internal()
+    }
+
+    pub(crate) fn is_node(&self) -> bool {
+        self.is_internal() && self.raw > (CHUNK_SIZE << 2)
+    }
+
+    pub(crate) fn is_sibling(&self) -> bool {
+        self.is_internal() && self.raw < (((CHUNK_SIZE - 1) << 2) | 2)
+    }
+
+    pub(crate) fn as_node<I: ItemEntry>(&self) -> Option<&RwLock<XNode<I>>> {
+        if self.is_node() {
+            unsafe {
+                let node_ref = &*((self.raw - 2) as *const RwLock<XNode<I>>);
+                Some(node_ref)
+            }
+        } else {
+            None
+        }
+    }
+
+    pub(crate) fn as_sibling(&self) -> Option<u8> {
+        if self.is_sibling() {
+            Some((self.raw >> 2).try_into().unwrap())
+        } else {
+            None
+        }
+    }
+}
+
+impl<I: ItemEntry, Type> PartialEq<OwnedEntry<I, Type>> for XEntry {
+    fn eq(&self, o: &OwnedEntry<I, Type>) -> bool {
+        self.raw == o.raw
+    }
+}

src/main.rs

@@ -0,0 +1,42 @@
+#![feature(pointer_is_aligned)]
+use core::prelude::v1;
+use std::sync::Arc;
+
+use entry::*;
+use mark::*;
+use node::*;
+use state::*;
+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);
+}

src/mark.rs

@@ -0,0 +1,47 @@
+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

@@ -0,0 +1,111 @@
+use std::{
+    marker::PhantomData,
+    sync::{Arc, Mutex, RwLock, Weak},
+};
+
+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>,
+}
+
+impl<I: ItemEntry> XNode<I> {
+    pub(crate) fn new(shift: u8, offset: u8, parent: XEntry) -> Self {
+        Self {
+            shift,
+            offset,
+            count: 0,
+            nr_value: 0,
+            parent: parent,
+            slots: [XEntry::EMPTY; CHUNK_SIZE],
+            marks: [Mark { inner: 0 }; 3],
+            _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]
+    }
+
+    pub(crate) const fn get_offset(&self, index: u64) -> u8 {
+        ((index >> self.shift as u64) & CHUNK_MASK as u64) as u8
+    }
+
+    pub(crate) fn entry(&self, index: u8) -> &XEntry {
+        &self.slots[index as usize]
+    }
+
+    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: OwnedEntry<I, Item>,
+    ) -> Option<OwnedEntry<I, Item>> {
+        let old_entry = OwnedEntry::<I, Item>::from_raw(self.slots[offset as usize]);
+        self.slots[offset as usize] = OwnedEntry::<I, Item>::into_raw(entry);
+        old_entry
+    }
+
+    pub(crate) fn max_index(&self) -> u64 {
+        ((CHUNK_SIZE as u64) << (self.shift as u64)) - 1
+    }
+
+    pub(crate) fn shift(&self) -> u8 {
+        self.shift
+    }
+
+    pub(crate) fn offset(&self) -> u8 {
+        self.offset
+    }
+
+    pub(crate) fn parent(&self) -> XEntry {
+        self.parent
+    }
+
+    pub(crate) fn set_offset(&mut self, offset: u8) {
+        self.offset = offset;
+    }
+
+    pub(crate) fn set_parent(&mut self, parent: XEntry) {
+        self.parent = parent;
+    }
+
+    pub(crate) fn set_shift(&mut self, shift: u8) {
+        self.shift = shift;
+    }
+}
+
+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);
+            }
+        }
+    }
+}

src/state.rs

@@ -0,0 +1,241 @@
+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: OwnedEntry<I, Item>,
+    ) -> Option<OwnedEntry<I, Item>> {
+        let op_entry = self.create(xa);
+        // TODO: Multi-index entry
+        if *op_entry == entry {
+            return Some(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);
+        let k = node_write.entry(self.offset);
+        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/xarray.rs

@@ -0,0 +1,122 @@
+use std::{
+    marker::PhantomData,
+    sync::{Arc, Mutex, RwLock},
+};
+
+use crate::*;
+pub const CHUNK_SHIFT: usize = 6;
+pub const CHUNK_SIZE: usize = 1 << CHUNK_SHIFT;
+pub const CHUNK_MASK: usize = CHUNK_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
+///
+/// # 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);
+/// ```
+///
+/// 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)>,
+}
+
+impl<I: ItemEntry, M: XMark> XArray<I, M> {
+    pub const fn new() -> Self {
+        Self {
+            head: XEntry::EMPTY,
+            _marker: PhantomData,
+        }
+    }
+
+    pub(crate) fn head(&self) -> &XEntry {
+        &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);
+        old_head
+    }
+
+    pub fn load<'a>(&'a self, index: u64) -> Option<I::Target<'a>> {
+        let mut cursor = self.cursor(index);
+        let entry = cursor.current();
+        unsafe { Some(I::load_item(entry)) }
+    }
+
+    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),
+        }
+    }
+}
+
+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)
+    }
+
+    pub fn key(&mut self) -> u64 {
+        self.xas.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, OwnedEntry::from_item(item));
+    }
+
+    pub fn key(&mut self) -> u64 {
+        self.xas.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);
+        }
+    }
+}