Concread

https://docs.rs/concread/0.5.10
Admin
Concread is a Rust library providing concurrently readable data structures using Copy-On-Write and...
Tokens:349,349
Snippets:2,660
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Test Data Creation (Reader)

Source: https://docs.rs/concread/0.5.10/src/concread/internals/lincowcell_async/mod.rs.html

Example implementation of `create_reader` for test data, creating a `TestDataReadTxn` from `TestData`.

```rust
impl LinCowCellCapable<TestDataReadTxn, TestDataWriteTxn> for TestData {
        fn create_reader(&self) -> TestDataReadTxn {
            TestDataReadTxn { x: self.x }
        }

        fn create_writer(&self) -> TestDataWriteTxn {
            TestDataWriteTxn { x: self.x }
        }

        fn pre_commit(
            &mut self,
            new: TestDataWriteTxn,
            _prev: &TestDataReadTxn,
        ) -> TestDataReadTxn {
            // Update self if needed.
            self.x = new.x;
            // return a new reader.
            TestDataReadTxn { x: new.x }
        }
    }
```

--------------------------------

### Initiate Async Read Transaction

Source: https://docs.rs/concread/0.5.10/src/concread/bptree/asynch.rs.html

Starts a read transaction for the BptreeMap, allowing concurrent reads and writes. This method is non-blocking.

```rust
pub fn read<'x>(&'x self) -> BptreeMapReadTxn<'x, K, V> {
        let inner = self.inner.read();
        BptreeMapReadTxn { inner }
    }
```

--------------------------------

### Initiate a Write Transaction

Source: https://docs.rs/concread/0.5.10/concread/hashtrie/struct.HashTrie.html

Start a mutable transaction on the HashTrie. This transaction is exclusive to the writer and runs concurrently with existing read transactions. Writes are serialized.

```rust
pub fn write(&self) -> HashTrieWriteTxn<'_, K, V>

```

--------------------------------

### LeafIter Test with Included Bound 0

Source: https://docs.rs/concread/0.5.10/src/concread/internals/bptree/iter.rs.html

Tests LeafIter starting with an inclusive bound of 0. Verifies that the iterator correctly yields elements starting from the first element greater than or equal to the bound.

```rust
let root: *mut Branch<usize, usize> =
            Node::new_branch(0, b1node as *mut _, b2node as *mut _);
        let mut test_iter: LeafIter<usize, usize> = LeafIter::new(root as *mut _, Included(&0));
        // Should be on the 10

        let l1ref = test_iter.next().unwrap();
        let r1ref = test_iter.next().unwrap();
        let l2ref = test_iter.next().unwrap();
        let r2ref = test_iter.next().unwrap();
        assert!(l1ref.min() == &10);
        assert!(r1ref.min() == &20);
        assert!(l2ref.min() == &30);
        assert!(r2ref.min() == &40);
        assert!(test_iter.next().is_none());
        // This drops everything.
        let _sb: SuperBlock<usize, usize> = SuperBlock::new_test(1, root as *mut _);
```

--------------------------------

### Initialize and Use CowCell

Source: https://docs.rs/concread/0.5.10/concread/cowcell/struct.CowCell.html

Demonstrates creating a CowCell, performing a read, then a write, and observing the effects on different read transactions. Requires T to implement Clone.

```rust
use concread::cowcell::CowCell;

let data: i64 = 0;
let cowcell = CowCell::new(data);

// Begin a read transaction
let read_txn = cowcell.read();
assert_eq!(*read_txn, 0);
{
    // Now create a write, and commit it.
    let mut write_txn = cowcell.write();
    *write_txn = 1;
    // Commit the change
    write_txn.commit();
}
// Show the previous generation still reads '0'
assert_eq!(*read_txn, 0);
let new_read_txn = cowcell.read();
// And a new read transaction has '1'
assert_eq!(*new_read_txn, 1);
```

--------------------------------

### HashTrieWriteTxn Methods

Source: https://docs.rs/concread/0.5.10/concread/hashtrie/asynch/struct.HashTrieWriteTxn.html

Provides methods for interacting with an active write transaction on a HashTrie, including getting, checking for keys, managing size, iterating, clearing, inserting, removing, and getting mutable references.

```APIDOC
## HashTrieWriteTxn Methods

### `get<Q>(&self, k: &Q) -> Option<&V>`
Retrieve a value from the map. If the value exists, a reference is returned as `Some(&V)`, otherwise if not present `None` is returned.

### `contains_key<Q>(&self, k: &Q) -> bool`
Assert if a key exists in the map.

### `len(&self) -> usize`
Returns the current number of k:v pairs in the tree.

### `is_empty(&self) -> bool`
Determine if the set is currently empty.

### `iter(&self) -> Iter<'_, K, V>`
Iterator over `(&K, &V)` of the set.

### `values(&self) -> ValueIter<'_, K, V>`
Iterator over &K.

### `keys(&self) -> KeyIter<'_, K, V>`
Iterator over &V.

### `clear(&mut self)`
Reset this map to an empty state. As this is within the transaction this change only takes effect once committed. Once cleared, you can begin adding new writes and changes, again, that will only be visible once committed.

### `insert(&mut self, k: K, v: V) -> Option<V>`
Insert or update a value by key. If the value previously existed it is returned as `Some(V)`. If the value did not previously exist this returns `None`.

### `remove(&mut self, k: &K) -> Option<V>`
Remove a key if it exists in the tree. If the value exists, we return it as `Some(V)`, and if it did not exist, we return `None`.

### `get_mut(&mut self, k: &K) -> Option<&mut V>`
Get a mutable reference to a value in the tree. This is correctly, and safely cloned before you attempt to mutate the value, isolating it from other transactions.

### `to_snapshot(&self) -> HashTrieReadSnapshot<'_, K, V>`
Create a read-snapshot of the current map. This does NOT guarantee the map may not be mutated during the read, so you MUST guarantee that no functions of the write txn are called while this snapshot is active.
```

--------------------------------

### Iter Usage Example

Source: https://docs.rs/concread/0.5.10/src/concread/internals/hashmap/iter.rs.html

Demonstrates creating and using the general Iter for a hashmap with two leaf nodes. Asserts the size hint and the total count of elements.

```rust
let lnode = create_leaf_node_full(10);
        let rnode = create_leaf_node_full(20);
        let root = Node::new_branch(0, lnode, rnode);
        let test_iter: Iter<usize, usize> = Iter::new(root as *mut _, H_CAPACITY * 2);

        assert!(test_iter.size_hint() == (H_CAPACITY * 2, Some(H_CAPACITY * 2)));
        assert!(test_iter.count() == H_CAPACITY * 2);
        // Iterate!
        // This drops everything.
        let _sb: SuperBlock<usize, usize> = SuperBlock::new_test(1, root as *mut _);
```

--------------------------------

### Initiate a Write Transaction

Source: https://docs.rs/concread/0.5.10/concread/bptree/struct.BptreeMap.html

Starts a write transaction, ensuring exclusive access for the writer while allowing concurrent reads. Writers are serialized.

```rust
pub fn write(&self) -> BptreeMapWriteTxn<'_, K, V>
```

--------------------------------

### Test Simple Create and Mutation

Source: https://docs.rs/concread/0.5.10/src/concread/internals/lincowcell_async/mod.rs.html

Demonstrates creating a LinCowCell, performing read and write transactions, mutating data within a write transaction, and observing commit behavior.

```rust
#[tokio::test]
    async fn test_simple_create() {
        let data = TestData { x: 0 };
        let cc = LinCowCell::new(data);

        let cc_rotxn_a = cc.read();
        println!("cc_rotxn_a -> {:?}", cc_rotxn_a);
        assert_eq!(cc_rotxn_a.work.data.x, 0);

        {
            /* Take a write txn */
            let mut cc_wrtxn = cc.write().await;
            println!("cc_wrtxn -> {:?}", cc_wrtxn);
            assert_eq!(cc_wrtxn.work.x, 0);
            assert_eq!(cc_wrtxn.as_ref().x, 0);
            {
                let mut_ptr = cc_wrtxn.get_mut();
                /* Assert it's 0 */
                assert_eq!(mut_ptr.x, 0);
                mut_ptr.x = 1;
                assert_eq!(mut_ptr.x, 1);
            }
            // Check we haven't mutated the old data.
            assert_eq!(cc_rotxn_a.work.data.x, 0);
        }
        // The writer is dropped here. Assert no changes.
        assert_eq!(cc_rotxn_a.work.data.x, 0);
        {
            /* Take a new write txn */
            let mut cc_wrtxn = cc.write().await;
            println!("cc_wrtxn -> {:?}", cc_wrtxn);
            assert_eq!(cc_wrtxn.work.x, 0);
            assert_eq!(cc_wrtxn.as_ref().x, 0);
            {
                let mut_ptr = cc_wrtxn.get_mut();
                /* Assert it's 0 */
                assert_eq!(mut_ptr.x, 0);
                mut_ptr.x = 2;
                assert_eq!(mut_ptr.x, 2);
            }
            // Check we haven't mutated the old data.
            assert_eq!(cc_rotxn_a.work.data.x, 0);
            // Now commit
            cc_wrtxn.commit();
        }
        // Should not be perceived by the old txn.
        assert_eq!(cc_rotxn_a.work.data.x, 0);
        let cc_rotxn_c = cc.read();
        // Is visible to the new one though.
        assert_eq!(cc_rotxn_c.work.data.x, 2);
    }
```

--------------------------------

### Advance Left Iterator for Start Bound

Source: https://docs.rs/concread/0.5.10/src/concread/internals/bptree/iter.rs.html

Positions the left iterator based on the start bound of a range. Handles inclusive and exclusive bounds, updating the internal index or advancing to the next leaf if necessary.

```rust
match range.start_bound() {
            Bound::Unbounded => {
                // Do nothing!
            }
            Bound::Included(k) => {
                if let Some((node, idx)) = left_iter.get_mut() {
                    let leaf = leaf_ref!(*node, K, V);
                    // eprintln!("Positioning Included with ... {:?} {:?}", leaf, idx);
                    match leaf.locate(k) {
                        Ok(fidx) | Err(fidx) => {
                            // eprintln!("Using, {}", fidx);
                            *idx = fidx;
                            // Done!
                        }
                    }
                } else {
                    // Do nothing, it's empty.
                }
            }
            Bound::Excluded(k) => {
                if let Some((node, idx)) = left_iter.get_mut() {
                    let leaf = leaf_ref!(*node, K, V);
                    // eprintln!("Positioning Excluded with ... {:?} {:?}", leaf, idx);
                    match leaf.locate(k) {
                        Ok(fidx) => {
                            // eprintln!("Excluding Using, {}", fidx);
                            *idx = fidx + 1;
                            if *idx >= leaf.count() {
                                if let Some((rnode, _)) = right_iter.get_mut() {
                                    // If the leaf iterators were in the same node before advancing left iterator
                                    // means that left iterator would be ahead of right iter so no elements left
                                    if rnode == node {
                                        left_iter.clear();
                                        right_iter.clear();
                                    }
                                }
                                // Okay, this means we overflowed to the next leaf, so just
                                // advanced the leaf iter to the start of the next
                                left_iter.next();
                            }
                            // Done
                        }
                        Err(fidx) => {
                            // eprintln!("Using, {}", fidx);
                            *idx = fidx;
                            // Done!
                        }
                    }
                } else {
                    // Do nothing, the leaf iter is empty.
                }
            }
        }
```

--------------------------------

### Create and Use CowCell

Source: https://docs.rs/concread/0.5.10/src/concread/cowcell/mod.rs.html

Demonstrates creating a CowCell, performing a read, then a write, and observing the consistency of old and new read transactions.

```rust
use concread::cowcell::CowCell;

let data: i64 = 0;
let cowcell = CowCell::new(data);

// Begin a read transaction
let read_txn = cowcell.read();
assert_eq!(*read_txn, 0);
{
    // Now create a write, and commit it.
    let mut write_txn = cowcell.write();
    *write_txn = 1;
    // Commit the change
    write_txn.commit();
}
// Show the previous generation still reads '0'
assert_eq!(*read_txn, 0);
let new_read_txn = cowcell.read();
// And a new read transaction has '1'
assert_eq!(*new_read_txn, 1);

```

--------------------------------

### keys

Source: https://docs.rs/concread/0.5.10/src/concread/bptree/impl.rs.html

Get an iterator over the keys `(&K)` in the tree.

```APIDOC
## keys

### Description
Provides an iterator over the keys `(&K)` of the map.

### Method
`KeyIter<'_, K, V>`

### Parameters
None

### Returns
An iterator yielding references to keys.
```

--------------------------------

### EbrCell Example: Read, Write, and Commit

Source: https://docs.rs/concread/0.5.10/src/concread/ebrcell/mod.rs.html

Demonstrates the basic usage of EbrCell, including creating a cell, initiating a read transaction, performing a write transaction, committing the change, and observing data consistency across different read generations.

```rust
use concread::ebrcell::EbrCell;

let data: i64 = 0;
let ebrcell = EbrCell::new(data);

// Begin a read transaction
let read_txn = ebrcell.read();
assert_eq!(*read_txn, 0);
{
    // Now create a write, and commit it.
    let mut write_txn = ebrcell.write();
    *write_txn = 1;
    // Commit the change
    write_txn.commit();
}
// Show the previous generation still reads '0'
assert_eq!(*read_txn, 0);
let new_read_txn = ebrcell.read();
// And a new read transaction has '1'
assert_eq!(*new_read_txn, 1);

```

--------------------------------

### values

Source: https://docs.rs/concread/0.5.10/src/concread/bptree/impl.rs.html

Get an iterator over the values `(&V)` in the tree.

```APIDOC
## values

### Description
Provides an iterator over the values `(&V)` of the map.

### Method
`ValueIter<'_, K, V>`

### Parameters
None

### Returns
An iterator yielding references to values.
```

--------------------------------

### LinCowCell::new

Source: https://docs.rs/concread/0.5.10/concread/internals/lincowcell_async/struct.LinCowCell.html

Creates a new instance of LinCowCell with the provided data.

```APIDOC
## new

### Description
Create a new linear 🐄 cell.

### Signature
```rust
pub fn new(data: T) -> Self
```
```

--------------------------------

### len

Source: https://docs.rs/concread/0.5.10/src/concread/bptree/impl.rs.html

Get the current number of key-value pairs in the tree.

```APIDOC
## len

### Description
Returns the current number of key-value pairs in the tree.

### Method
`usize`

### Parameters
None

### Returns
The number of elements in the tree.
```

--------------------------------

### type_id

Source: https://docs.rs/concread/0.5.10/concread/internals/bptree/iter/struct.Iter.html

Gets the `TypeId` of `self`. This is part of the `Any` trait implementation.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Source
Part of the `Any` trait implementation.
```

--------------------------------

### LeafIter Usage Example

Source: https://docs.rs/concread/0.5.10/src/concread/internals/hashmap/iter.rs.html

Demonstrates creating and iterating over leaf nodes using LeafIter. Asserts the size hint and the minimum values of the iterated elements. Ensures all elements are consumed.

```rust
let r1node = create_leaf_node_full(20);
        let l2node = create_leaf_node_full(30);
        let r2node = create_leaf_node_full(40);
        let b1node = Node::new_branch(0, l1node, r1node);
        let b2node = Node::new_branch(0, l2node, r2node);
        let root: *mut Branch<usize, usize> =
            Node::new_branch(0, b1node as *mut _, b2node as *mut _);
        let mut test_iter: LeafIter<usize, usize> = LeafIter::new(root as *mut _, true);

        assert!(test_iter.size_hint() == (4, Some(4)));
        let l1ref = test_iter.next().unwrap();
        let r1ref = test_iter.next().unwrap();
        let l2ref = test_iter.next().unwrap();
        let r2ref = test_iter.next().unwrap();
        assert!(l1ref.min() == 10);
        assert!(r1ref.min() == 20);
        assert!(l2ref.min() == 30);
        assert!(r2ref.min() == 40);
        assert!(test_iter.next().is_none());
        // This drops everything.
        let _sb: SuperBlock<usize, usize> = SuperBlock::new_test(1, root as *mut _);
```

--------------------------------

### take

Source: https://docs.rs/concread/0.5.10/concread/internals/bptree/mutiter/struct.RangeMutIter.html

Creates an iterator that yields the first `n` elements.

```APIDOC
## fn take(self, n: usize) -> Take<Self>

### Description
Creates an iterator that yields the first `n` elements, or fewer if the underlying iterator ends sooner.

### Parameters
#### Path Parameters
- **n** (usize) - Required - The maximum number of elements to yield.
```

--------------------------------

### iter

Source: https://docs.rs/concread/0.5.10/src/concread/bptree/impl.rs.html

Get an iterator over the key-value pairs `(&K, &V)` in the tree.

```APIDOC
## iter

### Description
Provides an iterator over the key-value pairs `(&K, &V)` of the map.

### Method
`Iter<'_, K, V>`

### Parameters
None

### Returns
An iterator yielding references to key-value pairs.
```

--------------------------------

### LinCowCell Read/Write Operations and GC Lifecycle

Source: https://docs.rs/concread/0.5.10/src/concread/internals/lincowcell/mod.rs.html

Illustrates creating a LinCowCell, performing multiple read and write operations, and observing the garbage collection count. This example is useful for understanding the lifecycle of data within LinCowCell and how modifications affect its state.

```rust
let data = TestGcWrapper { data: 0 };
        let cc = LinCowCell::new(data);

        // Open a read A.
        let cc_rotxn_a = cc.read();
        let cc_rotxn_a_2 = cc.read();
        // open a write, change and commit
        {
            let mut cc_wrtxn = cc.write();
            {
                let mut_ptr = cc_wrtxn.get_mut();
                mut_ptr.data += 1;
            }
            cc_wrtxn.commit();
        }
        // open a read B.
        let cc_rotxn_b = cc.read();
        // open a write, change and commit
        {
            let mut cc_wrtxn = cc.write();
            {
                let mut_ptr = cc_wrtxn.get_mut();
                mut_ptr.data += 1;
            }
            cc_wrtxn.commit();
        }
        // open a read C
        let cc_rotxn_c = cc.read();

        assert!(GC_COUNT.load(Ordering::Acquire) == 0);

        // drop B
        drop(cc_rotxn_b);

        // gc count should be 0.
        assert!(GC_COUNT.load(Ordering::Acquire) == 0);

        // drop C
        drop(cc_rotxn_c);

        // gc count should be 0
        assert!(GC_COUNT.load(Ordering::Acquire) == 0);

        // Drop the second A, should not trigger yet.
        drop(cc_rotxn_a_2);
        assert!(GC_COUNT.load(Ordering::Acquire) == 0);

        // drop A
        drop(cc_rotxn_a);

        // gc count should be 2 (A + B, C is still live)
        assert!(GC_COUNT.load(Ordering::Acquire) == 2);
```

--------------------------------

### Pointable::deref

Source: https://docs.rs/concread/0.5.10/concread/hashtrie/struct.HashTrieWriteTxn.html

Dereferences a pointer to get an immutable reference to the value.

```APIDOC
## unsafe fn deref<'a>(ptr: usize) -> &'a T

### Description
Dereferences the given pointer.

### Method
`deref`
```

--------------------------------

### Meta Data Get Count

Source: https://docs.rs/concread/0.5.10/src/concread/internals/bptree/node.rs.html

Retrieves the count from the node's metadata.

```rust
pub(crate) fn count(&self) -> usize {
        (self.0 & COUNT_MASK) as usize
    }
```

--------------------------------

### Begin Write Transaction

Source: https://docs.rs/concread/0.5.10/concread/internals/lincowcell/struct.LinCowCell.html

Initiates a write transaction on the LinCowCell. This provides exclusive access for writing.

```rust
pub fn write(&self) -> LinCowCellWriteTxn<'_, T, R, U>
```

--------------------------------

### Pointable::deref_mut

Source: https://docs.rs/concread/0.5.10/concread/hashtrie/struct.HashTrieWriteTxn.html

Mutably dereferences a pointer to get a mutable reference to the value.

```APIDOC
## unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

### Description
Mutably dereferences the given pointer.

### Method
`deref_mut`
```

--------------------------------

### Test HashMap basic write operations

Source: https://docs.rs/concread/0.5.10/src/concread/hashmap/mod.rs.html

Demonstrates basic write operations on a HashMap, including insert, extend, contains_key, get, get_mut, remove, clear, and commit.

```rust
#[test]
fn test_hashmap_basic_write() {
    let hmap: HashMap<usize, usize> = HashMap::new();
    let mut hmap_write = hmap.write();

    hmap_write.insert(10, 10);
    hmap_write.extend(vec![(15, 15)]);

    assert!(hmap_write.contains_key(&10));
    assert!(hmap_write.contains_key(&15));
    assert!(!hmap_write.contains_key(&20));

    assert!(hmap_write.get(&10) == Some(&10));
    {
        let v = hmap_write.get_mut(&10).unwrap();
        *v = 11;
    }
    assert!(hmap_write.get(&10) == Some(&11));

    assert!(hmap_write.remove(&10).is_some());
    assert!(!hmap_write.contains_key(&10));
    assert!(hmap_write.contains_key(&15));

    assert!(hmap_write.remove(&30).is_none());
    assert!(!hmap_write.is_empty());

    assert_eq!(hmap_write.keys().count(), 1);

    hmap_write.clear();
    assert!(!hmap_write.contains_key(&10));
    assert!(!hmap_write.contains_key(&15));
    hmap_write.commit();
}
```

--------------------------------

### CursorReadOps Implementation: Get Root Pointer

Source: https://docs.rs/concread/0.5.10/src/concread/internals/hashtrie/cursor.rs.html

Returns the pointer to the root of the hash trie.

```rust
fn get_root_ptr(&self) -> Ptr {
        self.root
    }
```

--------------------------------

### Basic async HashTrie write operations

Source: https://docs.rs/concread/0.5.10/src/concread/hashtrie/asynch.rs.html

Demonstrates basic write operations on an async HashTrie, including insert, contains_key, get, get_mut, remove, and clear. The changes are committed at the end.

```rust
async fn test_hashtrie_basic_write() {
        let hmap: HashTrie<usize, usize> = HashTrie::new();
        let mut hmap_write = hmap.write().await;

        hmap_write.insert(10, 10);
        hmap_write.insert(15, 15);

        assert!(hmap_write.contains_key(&10));
        assert!(hmap_write.contains_key(&15));
        assert!(!hmap_write.contains_key(&20));

        assert!(hmap_write.get(&10) == Some(&10));
        {
            let v = hmap_write.get_mut(&10).unwrap();
            *v = 11;
        }
        assert!(hmap_write.get(&10) == Some(&11));

        assert!(hmap_write.remove(&10).is_some());
        assert!(!hmap_write.contains_key(&10));
        assert!(hmap_write.contains_key(&15));

        assert!(hmap_write.remove(&30).is_none());

        hmap_write.clear();
        assert!(!hmap_write.contains_key(&10));
        assert!(!hmap_write.contains_key(&15));
        hmap_write.commit();
    }
```

--------------------------------

### Pointer Initialization

Source: https://docs.rs/concread/0.5.10/concread/bptree/asynch/struct.BptreeMapWriteTxn.html

Initialize a BptreeMapWriteTxn using a pointer-based approach.

```APIDOC
## unsafe fn init(init: <T as Pointable>::Init) -> usize

### Description
Initializes a with the given initializer.

### Method
`init`
```

--------------------------------

### Get Mutable Inner

Source: https://docs.rs/concread/0.5.10/src/concread/internals/lincowcell_async/mod.rs.html

Provides mutable access to the inner data of a write transaction.

```APIDOC
## get_mut

### Description
Returns a mutable reference to the inner data (`U`) of the `LinCowCellWriteTxn`.

### Method
`get_mut(&mut self) -> &mut U`

### Parameters
None

### Returns
A mutable reference to the inner data (`U`).
```

--------------------------------

### KeyIter Nightly Experimental APIs

Source: https://docs.rs/concread/0.5.10/concread/internals/bptree/iter/struct.KeyIter.html

Highlights experimental APIs available only on nightly Rust toolchains, including `advance_back_by`, `next_chunk`, and `advance_by`.

```APIDOC
## Nightly Experimental APIs for KeyIter

### `advance_back_by(n: usize)`

🔬 This is a nightly-only experimental API. (`iter_advance_by`)
Advances the iterator from the back by `n` elements.

- **Parameters**:
  - `n` (usize): The number of elements to advance by from the back.
- **Return**: `Result<(), NonZero<usize>>`

### `next_chunk<const N: usize>(&mut self)`

🔬 This is a nightly-only experimental API. (`iter_next_chunk`)
Advances the iterator and returns an array containing the next `N` values.

- **Type Parameters**:
  - `N` (const usize): The size of the array to return.
- **Return**: `Result<[Self::Item; N], IntoIter<Self::Item, N>>`

### `advance_by(n: usize)`

🔬 This is a nightly-only experimental API. (`iter_advance_by`)
Advances the iterator by `n` elements.

- **Parameters**:
  - `n` (usize): The number of elements to advance by.
- **Return**: `Result<(), NonZero<usize>>`
```

--------------------------------

### Get HashMap Length

Source: https://docs.rs/concread/0.5.10/src/concread/hashmap/impl.rs.html

Returns the number of key-value pairs currently stored in the HashMap.

```rust
pub fn len(&self) -> usize {
    self.inner.as_ref().len()
}
```

--------------------------------

### Default ARCacheBuilder implementation

Source: https://docs.rs/concread/0.5.10/concread/arcache/struct.ARCacheBuilder.html

Provides the default value for ARCacheBuilder, which can be used as a starting point for configuration.

```rust
fn default() -> Self
```

--------------------------------

### Basic HashTrie Read and Write Operations

Source: https://docs.rs/concread/0.5.10/src/concread/hashtrie/mod.rs.html

Illustrates concurrent read and write operations on a HashTrie. Shows how writes are committed and reflected in subsequent reads, and how reads observe data before writes are committed.

```rust
let hmap: HashTrie<usize, usize> = HashTrie::new();
        // using try_write to get full coverage
        let mut hmap_w1 = hmap.try_write().unwrap();
        // just coverage things
        assert!(hmap_w1.is_empty());
        hmap_w1.insert(10, 10);
        // just coverage things
        hmap_w1.extend([(15, 15)]);
        assert!(!hmap_w1.is_empty());
        hmap_w1.commit();

        assert_eq!(hmap.read().len(), 2);

        let hmap_r1 = hmap.read();
        assert!(!hmap_r1.is_empty());
        assert_eq!(hmap_r1.len(), 2);
        assert!(hmap_r1.contains_key(&10));
        assert!(hmap_r1.contains_key(&15));
        assert!(!hmap_r1.contains_key(&20));

        let mut hmap_w2 = hmap.write();
        hmap_w2.insert(20, 20);
        hmap_w2.commit();

        assert!(hmap_r1.contains_key(&10));
        assert!(hmap_r1.contains_key(&15));
        assert!(!hmap_r1.contains_key(&20));

        let hmap_r2 = hmap.read();
        assert!(hmap_r2.contains_key(&10));
        assert!(hmap_r2.contains_key(&15));
        assert!(hmap_r2.contains_key(&20));
```

--------------------------------

### Meta Data Get Transaction ID

Source: https://docs.rs/concread/0.5.10/src/concread/internals/bptree/node.rs.html

Retrieves the transaction ID from the node's metadata.

```rust
pub(crate) fn get_txid(&self) -> u64 {
        (self.0 & TXID_MASK) >> TXID_SHF
    }
```

--------------------------------

### LinCowCell::new

Source: https://docs.rs/concread/0.5.10/concread/internals/lincowcell/struct.LinCowCell.html

Creates a new LinCowCell instance with the provided data. This is the entry point for initializing a concurrently accessible cell.

```APIDOC
## new

### Description
Create a new linear 🐄 cell.

### Signature
```rust
pub fn new(data: T) -> Self
```

### Parameters
* `data`: The data of type `T` to be stored in the cell.
```

--------------------------------

### Basic HashTrie Write Operations

Source: https://docs.rs/concread/0.5.10/src/concread/hashtrie/mod.rs.html

Demonstrates basic write operations on a HashTrie, including insertion, checking for keys, getting values, modifying values, removing entries, and clearing the trie. Includes committing changes.

```rust
let hmap: HashTrie<usize, usize> = HashTrie::new();
        let mut hmap_write = hmap.write();

        hmap_write.insert(10, 10);
        hmap_write.insert(15, 15);

        assert!(hmap_write.contains_key(&10));
        assert!(hmap_write.contains_key(&15));
        assert!(!hmap_write.contains_key(&20));

        assert!(hmap_write.get(&10) == Some(&10));
        {
            let v = hmap_write.get_mut(&10).unwrap();
            *v = 11;
        }
        assert!(hmap_write.get(&10) == Some(&11));

        assert!(hmap_write.remove(&10).is_some());
        assert!(!hmap_write.contains_key(&10));
        assert!(hmap_write.contains_key(&15));

        assert!(hmap_write.remove(&30).is_none());

        hmap_write.clear();
        assert!(!hmap_write.contains_key(&10));
        assert!(!hmap_write.contains_key(&15));
        hmap_write.commit();
```

--------------------------------

### Get Minimum Value

Source: https://docs.rs/concread/0.5.10/src/concread/internals/hashmap/node.rs.html

Retrieves the minimum value stored in the node. This operation is recursive and cannot be inlined.

```rust
pub(crate) fn min(&self) -> u64 {
        debug_assert_branch!(self);
        unsafe { (*self.nodes[0]).min() }
```

--------------------------------

### contains_key

Source: https://docs.rs/concread/0.5.10/src/concread/arcache/mod.rs.html

Determines if the cache contains the specified key by attempting to retrieve it using the `get` method.

```APIDOC
## contains_key<Q>

### Description
Determine if this cache contains the following key.

### Method
`pub fn contains_key<Q>(&mut self, k: &Q) -> bool`

### Type Parameters
- `Q`: The type to which the key `K` can be borrowed.

### Parameters
- **k** (`&Q`): The key to check for existence in the cache.

### Return Value
- `bool`: `true` if the key exists in the cache, `false` otherwise.

### Generic Constraints
- `K: Borrow<Q>`
- `Q: Hash + Eq + Ord + ?Sized`
```

--------------------------------

### Initialize and Use RevLeafIter with Unbounded

Source: https://docs.rs/concread/0.5.10/src/concread/internals/bptree/iter.rs.html

Demonstrates initializing `RevLeafIter` with a root node and `Unbounded` to iterate through all leaf nodes in reverse. Asserts the order and values of retrieved leaf node references.

```rust
let b2node = Node::new_branch(0, l2node, r2node);
let root: *mut Branch<usize, usize> =
    Node::new_branch(0, b1node as *mut _, b2node as *mut _);
let mut test_iter: RevLeafIter<usize, usize> = RevLeafIter::new(root as *mut _, Unbounded);

let r2ref = test_iter.next().unwrap();
let l2ref = test_iter.next().unwrap();
let r1ref = test_iter.next().unwrap();
let l1ref = test_iter.next().unwrap();
assert!(r2ref.min() == &40);
assert!(l2ref.min() == &30);
assert!(r1ref.min() == &20);
assert!(l1ref.min() == &10);
assert!(test_iter.next().is_none());
// This drops everything.
let _sb: SuperBlock<usize, usize> = SuperBlock::new_test(1, root as *mut _);
```

--------------------------------

### CursorReadOps Implementation: Get Length

Source: https://docs.rs/concread/0.5.10/src/concread/internals/hashtrie/cursor.rs.html

Returns the number of elements currently stored in the hash trie.

```rust
fn len(&self) -> usize {
        self.length
    }
```

--------------------------------

### RevLeafIter with Branch Node and Exact Max Bound

Source: https://docs.rs/concread/0.5.10/src/concread/internals/bptree/iter.rs.html

Demonstrates `RevLeafIter` initialization with a branch node and an upper bound exactly matching a value in the rightmost leaf node. Asserts correct iteration order and values.

```rust
let lnode = create_leaf_node_full(10);
let rnode = create_leaf_node_full(20);
eprintln!("{:?}, {:?}", lnode, rnode);

let root = Node::new_branch(0, lnode, rnode);
let mut test_iter: RevLeafIter<usize, usize> =
    RevLeafIter::new(root as *mut _, Included(&20));
// Cursor should be positioned on the node with "20"

let rref = test_iter.next().unwrap();
let lref = test_iter.next().unwrap();
assert!(rref.min() == &20);
assert!(lref.min() == &10);
assert!(test_iter.next().is_none());
// This drops everything.
let _sb: SuperBlock<usize, usize> = SuperBlock::new_test(1, root as *mut _);
```

--------------------------------

### get

Source: https://docs.rs/concread/0.5.10/src/concread/bptree/impl.rs.html

Retrieve a value from the tree by key. Returns `Some(&V)` if the value exists, otherwise `None`.

```APIDOC
## get

### Description
Retrieve a value from the tree by key. If the value exists, a reference is returned as `Some(&V)`, otherwise if not present `None` is returned.

### Method
`Option<&V>`

### Parameters
- **k** (`&Q`): The key to search for. `K` must implement `Borrow<Q>` and `Q` must implement `Ord + ?Sized`.

### Returns
- `Some(&V)`: A reference to the value if the key exists.
- `None`: If the key does not exist.
```

--------------------------------

### Basic async HashTrie read and write operations

Source: https://docs.rs/concread/0.5.10/src/concread/hashtrie/asynch.rs.html

Tests basic read and write operations on an async HashTrie, showing how to commit writes and then perform reads.

```rust
async fn test_hashtrie_basic_read_write() {
        let hmap: HashTrie<usize, usize> = HashTrie::new();
        let mut hmap_w1 = hmap.write().await;
        hmap_w1.insert(10, 10);
        hmap_w1.insert(15, 15);
        hmap_w1.commit();

        let hmap_r1 = hmap.read();

```

--------------------------------

### Iter Usage with Multiple Branches

Source: https://docs.rs/concread/0.5.10/src/concread/internals/hashmap/iter.rs.html

Illustrates creating and using the general Iter for a more complex tree structure with multiple branches. Asserts the size hint and the total count of elements.

```rust
let l1node = create_leaf_node_full(10);
        let r1node = create_leaf_node_full(20);
        let l2node = create_leaf_node_full(30);
        let r2node = create_leaf_node_full(40);
        let b1node = Node::new_branch(0, l1node, r1node);
        let b2node = Node::new_branch(0, l2node, r2node);
        let root: *mut Branch<usize, usize> =
            Node::new_branch(0, b1node as *mut _, b2node as *mut _);
        let test_iter: Iter<usize, usize> = Iter::new(root as *mut _, H_CAPACITY * 4);

        // println!("{:?}", test_iter.size_hint());

        assert!(test_iter.size_hint() == (H_CAPACITY * 4, Some(H_CAPACITY * 4)));
        assert!(test_iter.count() == H_CAPACITY * 4);
        // This drops everything.
        let _sb: SuperBlock<usize, usize> = SuperBlock::new_test(1, root as *mut _);
```

--------------------------------

### Dereference Pointer

Source: https://docs.rs/concread/0.5.10/concread/bptree/asynch/struct.BptreeMap.html

Dereferences a raw pointer to get an immutable reference to the object. This is an unsafe operation.

```rust
unsafe fn deref<'a>(ptr: usize) -> &'a T
```

--------------------------------

### Get Snapshot Size

Source: https://docs.rs/concread/0.5.10/concread/bptree/asynch/struct.BptreeMapReadSnapshot.html

Returns the total number of key-value pairs currently stored in the snapshot.

```rust
pub fn len(&self) -> usize
```

--------------------------------

### Leaf Node Get Count

Source: https://docs.rs/concread/0.5.10/src/concread/internals/bptree/node.rs.html

Retrieves the count of elements in a leaf node. Asserts that the node is a leaf.

```rust
pub(crate) fn count(&self) -> usize {
        debug_assert_leaf!(self);
        self.meta.count()
    }
```

--------------------------------

### EbrCell Usage Example

Source: https://docs.rs/concread/0.5.10/concread/ebrcell/struct.EbrCell.html

Demonstrates creating an EbrCell, performing a read, then a write operation, and observing the consistency of data across different read transactions.

```rust
use concread::ebrcell::EbrCell;

let data: i64 = 0;
let ebrcell = EbrCell::new(data);

// Begin a read transaction
let read_txn = ebrcell.read();
assert_eq!(*read_txn, 0);
{
    // Now create a write, and commit it.
    let mut write_txn = ebrcell.write();
    *write_txn = 1;
    // Commit the change
    write_txn.commit();
}
// Show the previous generation still reads '0'
assert_eq!(*read_txn, 0);
let new_read_txn = ebrcell.read();
// And a new read transaction has '1'
assert_eq!(*new_read_txn, 1);
```

--------------------------------

### Getting Metadata Slots

Source: https://docs.rs/concread/0.5.10/src/concread/internals/hashmap/node.rs.html

Retrieves the number of slots from the metadata. The count is extracted by masking the relevant bits.

```rust
    #[inline(always)]
    pub(crate) fn slots(&self) -> usize {
        (self.0 & COUNT_MASK) as usize
    }
```

--------------------------------

### Serialize and Deserialize HashMap with Serde

Source: https://docs.rs/concread/0.5.10/src/concread/hashmap/mod.rs.html

Shows how to serialize a HashMap to JSON and deserialize it back using the `serde_json` crate. Requires the `serde` feature to be enabled.

```rust
let hmap: HashMap<usize, usize> = vec![(10, 11), (15, 16), (20, 21)].into_iter().collect();

let value = serde_json::to_value(&hmap).unwrap();
assert_eq!(value, serde_json::json!({ "10": 11, "15": 16, "20": 21 }));

let hmap: HashMap<usize, usize> = serde_json::from_value(value).unwrap();
let mut vec: Vec<(usize, usize)> = hmap.read().iter().map(|(k, v)| (*k, *v)).collect();
vec.sort_unstable();
assert_eq!(vec, [(10, 11), (15, 16), (20, 21)]);
```

--------------------------------

### CursorReadOps Implementation: Get Transaction ID

Source: https://docs.rs/concread/0.5.10/src/concread/internals/hashtrie/cursor.rs.html

Returns the unique transaction ID associated with the current cursor.

```rust
fn get_txid(&self) -> u64 {
        self.txid
    }
```

--------------------------------

### Branch Node Creation and Verification

Source: https://docs.rs/concread/0.5.10/src/concread/internals/bptree/node.rs.html

Demonstrates the creation of a new branch node, linking two leaf nodes. Includes verification of the branch's integrity and checks for the minimum and maximum key values within its descendants.

```rust
        let left: *mut Leaf<usize, usize> = Node::new_leaf(1);
        let left_ref = unsafe { &mut *left };
        let right: *mut Leaf<usize, usize> = Node::new_leaf(1);
        let right_ref = unsafe { &mut *right };

        // add kvs to l and r
        for kv in 0..L_CAPACITY {
            left_ref.insert_or_update(kv + 10, kv + 10);
            right_ref.insert_or_update(kv + 20, kv + 20);
        }
        // create branch
        let branch: *mut Branch<usize, usize> = Node::new_branch(
            1,
            left as *mut Node<usize, usize>,
            right as *mut Node<usize, usize>,
        );
        // verify
        assert!(Branch::<usize, usize>::verify_raw(branch));
        // Test .min works on our descendants
        assert!(unsafe { *Branch::<usize, usize>::min_raw(branch) } == 10);
        // Test .max works on our descendants.
        assert!(unsafe { *Branch::<usize, usize>::max_raw(branch) } == (20 + L_CAPACITY - 1));
        // Get some k within the leaves.
        assert!(
```

--------------------------------

### HashTrie Methods

Source: https://docs.rs/concread/0.5.10/src/concread/hashtrie/impl.rs.html

Provides methods for interacting with the HashTrie, such as getting, inserting, removing, and iterating over key-value pairs.

```APIDOC
## get_prehashed<Q>

### Description
Retrieves a value from the map using a pre-hashed key.

### Signature
`pub(crate) fn get_prehashed<Q>(&self, k: &Q, k_hash: u64) -> Option<&V>`

### Type Parameters
- `Q`: The type of the key to search for, must implement `Hash`, `Eq`, and `?Sized`.

### Parameters
- `k`: A reference to the key to search for.
- `k_hash`: The pre-calculated hash of the key.

### Returns
- `Some(&V)` if the key exists, `None` otherwise.

## get<Q>

### Description
Retrieves a value from the map. If the value exists, a reference is returned as `Some(&V)`, otherwise if not present `None` is returned.

### Signature
`pub fn get<Q>(&self, k: &Q) -> Option<&V>`

### Type Parameters
- `Q`: The type of the key to search for, must implement `Hash`, `Eq`, and `?Sized`.

### Parameters
- `k`: A reference to the key to search for.

### Returns
- `Some(&V)` if the key exists, `None` otherwise.

## contains_key<Q>

### Description
Asserts if a key exists in the map.

### Signature
`pub fn contains_key<Q>(&self, k: &Q) -> bool`

### Type Parameters
- `Q`: The type of the key to search for, must implement `Hash`, `Eq`, and `?Sized`.

### Parameters
- `k`: A reference to the key to search for.

### Returns
- `true` if the key exists, `false` otherwise.

## len

### Description
Returns the current number of key-value pairs in the tree.

### Signature
`pub fn len(&self) -> usize`

### Returns
- The number of key-value pairs.

## is_empty

### Description
Determines if the set is currently empty.

### Signature
`pub fn is_empty(&self) -> bool`

### Returns
- `true` if the set is empty, `false` otherwise.

## iter

### Description
Returns an iterator over `(&K, &V)` of the set.

### Signature
`pub fn iter(&self) -> Iter<'_, K, V>`

### Returns
- An iterator over key-value pairs.

## values

### Description
Returns an iterator over `&K`.

### Signature
`pub fn values(&self) -> ValueIter<'_, K, V>`

### Returns
- An iterator over keys.

## keys

### Description
Returns an iterator over `&V`.

### Signature
`pub fn keys(&self) -> KeyIter<'_, K, V>`

### Returns
- An iterator over values.

## clear

### Description
Resets this map to an empty state. This change only takes effect once committed. Once cleared, you can begin adding new writes and changes, again, that will only be visible once committed.

### Signature
`pub fn clear(&mut self)`

## insert

### Description
Inserts or updates a value by key. If the value previously existed it is returned as `Some(V)`. If the value did not previously exist this returns `None`.

### Signature
`pub fn insert(&mut self, k: K, v: V) -> Option<V>`

### Parameters
- `k`: The key to insert or update.
- `v`: The value to associate with the key.

### Returns
- `Some(V)` if the key previously existed, `None` otherwise.

## remove

### Description
Removes a key if it exists in the tree. If the value exists, we return it as `Some(V)`, and if it did not exist, we return `None`.

### Signature
`pub fn remove(&mut self, k: &K) -> Option<V>`

### Parameters
- `k`: A reference to the key to remove.

### Returns
- `Some(V)` if the key existed and was removed, `None` otherwise.

## get_mut

### Description
Gets a mutable reference to a value in the tree. This is correctly and safely cloned before you attempt to mutate the value, isolating it from other transactions.

### Signature
`pub fn get_mut(&mut self, k: &K) -> Option<&mut V>`

### Parameters
- `k`: A reference to the key to get a mutable reference to.

### Returns
- `Some(&mut V)` if the key exists, `None` otherwise.

## to_snapshot

### Description
Creates a read-snapshot of the current map. This does NOT guarantee the map may not be mutated during the read, so you MUST guarantee that no functions of the write txn are called while this snapshot is active.

### Signature
`pub fn to_snapshot(&self) -> HashTrieReadSnapshot<'_, K, V>`

### Returns
- A `HashTrieReadSnapshot` of the current map.
```

--------------------------------

### Begin Write Transaction

Source: https://docs.rs/concread/0.5.10/concread/cowcell/asynch/struct.CowCell.html

Initiates an asynchronous write transaction, returning a write guard. Changes made through this guard are local and only become visible to readers after a commit.

```rust
pub async fn write<'x>(&'x self) -> CowCellWriteTxn<'x, T>
```

--------------------------------

### Initiate Async Write Transaction

Source: https://docs.rs/concread/0.5.10/src/concread/hashmap/asynch.rs.html

Starts an asynchronous write transaction. This provides exclusive access for modifications and is concurrent with existing reads. Use `await` as it may need to wait for active readers to complete.

```rust
pub async fn write<'x>(&'x self) -> HashMapWriteTxn<'x, K, V> {
        let inner = self.inner.write().await;
        HashMapWriteTxn { inner }
    }
```

--------------------------------

### Get Length of Doubly Linked List

Source: https://docs.rs/concread/0.5.10/src/concread/arcache/ll.rs.html

Returns the current number of elements in the doubly linked list.

```rust
    pub(crate) fn len(&self) -> usize {
        self.size
    }
```

--------------------------------

### Async HashTrie Basic Read Snapshot

Source: https://docs.rs/concread/0.5.10/src/concread/hashtrie/asynch.rs.html

Illustrates creating a snapshot of an asynchronous HashTrie during a write operation. The snapshot reflects the state at the time of creation.

```rust
    let snap = hmap_w1.to_snapshot();
    assert!(snap.contains_key(&10));
    assert!(snap.contains_key(&15));
    assert!(!snap.contains_key(&20));
```

--------------------------------

### LLNodeOwned: Get Mutable Reference to Key

Source: https://docs.rs/concread/0.5.10/src/concread/arcache/ll.rs.html

Provides a mutable reference to the key stored within the `LLNodeOwned`.

```rust
fn as_mut(&mut self) -> &mut K {
    unsafe { &mut *(*self.inner).k.as_mut_ptr() }
}
```
Tokens:
Raw