Scalable Concurrent Containers

https://github.com/wvwwvwwv/scalable-concurrent-containers
Admin
A collection of high-performance, scalable, concurrent, and asynchronous containers and utilities...
Tokens:4,022
Snippets:18
Trust Score:7.8
License:Apache-2.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Using Queue Container in Rust

Source: https://github.com/wvwwvwwv/scalable-concurrent-containers/blob/main/README.md

This example demonstrates the first-in-first-out (FIFO) behavior of the `Queue` container. It shows pushing elements, conditionally pushing elements based on the current state of the queue head using `push_if`, and popping elements in the order they were inserted.

```rust
use scc::Queue;

let queue: Queue<usize> = Queue::default();

queue.push(1);
assert!(queue.push_if(2, |e| e.map_or(false, |x| **x == 1)).is_ok());
assert!(queue.push_if(3, |e| e.map_or(false, |x| **x == 1)).is_err());
assert_eq!(queue.pop().map(|e| **e), Some(1));
assert_eq!(queue.pop().map(|e| **e), Some(2));
assert!(queue.pop().is_none());
```

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

### Using HashCache in Rust

Source: https://github.com/wvwwvwwv/scalable-concurrent-containers/blob/main/README.md

This snippet demonstrates the basic usage of `HashCache`. It shows initialization with capacity, putting and getting key-value pairs, checking capacity range, and removing an entry. It also implicitly shows the LRU eviction behavior in a full bucket.

```rust
use scc::HashCache;

let hashcache: HashCache<u64, u32> = HashCache::with_capacity(100, 2000);

/// The capacity cannot exceed the maximum capacity.
assert_eq!(hashcache.capacity_range(), 128..=2048);

/// If the bucket corresponding to `1` or `2` is full, the LRU entry will be evicted.
assert!(hashcache.put(1, 0).is_ok());
assert!(hashcache.put(2, 0).is_ok());

/// `1` becomes the most recently accessed entry in the bucket.
assert!(hashcache.get(&1).is_some());

/// An entry can be normally removed.
assert_eq!(hashcache.remove(&2).unwrap(), (2, 0));
```

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

### Performing Basic TreeIndex Operations in Rust

Source: https://github.com/wvwwvwwv/scalable-concurrent-containers/blob/main/README.md

This example shows how to initialize a `TreeIndex`, insert a key-value pair, perform lock-free reads using `peek_with`, remove an entry, and initiate asynchronous insertion and conditional removal operations. It highlights the non-blocking nature of read access.

```rust
use scc::TreeIndex;

let treeindex: TreeIndex<u64, u32> = TreeIndex::new();

assert!(treeindex.insert(1, 2).is_ok());

// `peek` and `peek_with` are lock-free.
assert_eq!(treeindex.peek_with(&1, |_, v| *v).unwrap(), 2);
assert!(treeindex.remove(&1));

let future_insert = treeindex.insert_async(2, 3);
let future_remove = treeindex.remove_if_async(&1, |v| *v == 2);
```

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

### Using the Entry API for HashMap in Rust

Source: https://github.com/wvwwvwwv/scalable-concurrent-containers/blob/main/README.md

This example illustrates the use of the `Entry` API for `scc::HashMap`, which provides a more convenient way to handle operations that depend on whether a key already exists. It demonstrates `or_insert` to insert a value only if the key is absent and `and_modify` combined with `or_insert` for conditional modification or insertion.

```Rust
use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

hashmap.entry(3).or_insert(7);
assert_eq!(hashmap.read(&3, |_, v| *v), Some(7));

hashmap.entry(4).and_modify(|v| { *v += 1 }).or_insert(5);
assert_eq!(hashmap.read(&4, |_, v| *v), Some(5));
```

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

### Performing Lock-Free Reads and Async Operations on HashIndex in Rust

Source: https://github.com/wvwwvwwv/scalable-concurrent-containers/blob/main/README.md

This example focuses on the read-optimized aspects of `scc::HashIndex`, specifically the lock-free `peek` and `peek_with` methods. It also demonstrates basic insertion and asynchronous removal using `insert_async` and `remove_if_async`, illustrating the hybrid nature of HashIndex operations.

```Rust
use scc::HashIndex;

let hashindex: HashIndex<u64, u32> = HashIndex::default();

assert!(hashindex.insert(1, 0).is_ok());

// `peek` and `peek_with` are lock-free.
assert_eq!(hashindex.peek_with(&1, |_, v| *v).unwrap(), 0);

let future_insert = hashindex.insert_async(2, 1);
let future_remove = hashindex.remove_if_async(&1, |_| true);
```

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

### Updating Entries using HashIndex Entry API in Rust

Source: https://github.com/wvwwvwwv/scalable-concurrent-containers/blob/main/README.md

This snippet shows how to update existing entries in an `scc::HashIndex` using its `Entry` API (`get`). It demonstrates two ways to update: replacing the entry with a new version using `update`, and performing an in-place update using `get_mut`, noting the use of `unsafe` for the latter.

```Rust
use scc::HashIndex;

let hashindex: HashIndex<u64, u32> = HashIndex::default();
assert!(hashindex.insert(1, 1).is_ok());

if let Some(mut o) = hashindex.get(&1) {
    // Create a new version of the entry.
    o.update(2);
};

if let Some(mut o) = hashindex.get(&1) {
    // Update the entry in place.
    unsafe { *o.get_mut() = 3; }
};
```

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

### Scanning a Range in TreeIndex in Rust

Source: https://github.com/wvwwvwwv/scalable-concurrent-containers/blob/main/README.md

This example illustrates how to query a specific range of keys within a `TreeIndex` using the `range` method. Like `iter`, `range` is lock-free and requires an `ebr::Guard`. It demonstrates counting entries in different range specifications (exclusive and inclusive ends).

```rust
use scc::ebr::Guard;
use scc::TreeIndex;

let treeindex: TreeIndex<u64, u32> = TreeIndex::new();

for i in 0..10 {
    assert!(treeindex.insert(i, 10).is_ok());
}

let guard = Guard::new();

assert_eq!(treeindex.range(1..1, &guard).count(), 0);
assert_eq!(treeindex.range(4..8, &guard).count(), 4);
assert_eq!(treeindex.range(4..=8, &guard).count(), 5);
```

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

### Migrating Hash* ForEach Method Rust

Source: https://github.com/wvwwvwwv/scalable-concurrent-containers/blob/main/CHANGELOG.md

This Rust snippet shows how to replace the removed `Hash*::for_each` method with the `HashMap::retain` method, which serves a similar purpose of iterating over and potentially modifying elements in the collection. The example modifies each value in the map. This requires the `scc::HashMap` type.

```Rust
use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();
assert!(hashmap.insert(1, 1).is_ok());

// hashmap.for_each(|_, v| { *v = 2; });
hashmap.retain(|_, v| { *v = 2; true });
```

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

### Implementing and Using LinkedList Trait in Rust

Source: https://github.com/wvwwvwwv/scalable-concurrent-containers/blob/main/README.md

This example shows how to define a custom struct `L` that implements the `LinkedList` trait. It demonstrates creating list nodes using `AtomicShared` and `Shared`, pushing a new node to the back, marking a node, traversing the list using `next_ptr`, and deleting a node to make it invisible.

```rust
use scc::ebr::{AtomicShared, Guard, Shared};
use scc::LinkedList;
use std::sync::atomic::Ordering::Relaxed;

#[derive(Default)]
struct L(AtomicShared<L>, usize);
impl LinkedList for L {
    fn link_ref(&self) -> &AtomicShared<L> {
        &self.0
    }
}

let guard = Guard::new();

let head: L = L::default();
let tail: Shared<L> = Shared::new(L(AtomicShared::null(), 1));

// A new entry is pushed.
assert!(head.push_back(tail.clone(), false, Relaxed, &guard).is_ok());
assert!(!head.is_marked(Relaxed));

// Users can mark a flag on an entry.
head.mark(Relaxed);
assert!(head.is_marked(Relaxed));

// `next_ptr` traverses the linked list.
let next_ptr = head.next_ptr(Relaxed, &guard);
assert_eq!(next_ptr.as_ref().unwrap().1, 1);

// Once `tail` is deleted, it becomes invisible.
tail.delete_self(Relaxed);
assert!(head.next_ptr(Relaxed, &guard).is_null());
```

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

### Iterating HashIndex Entries with ebr::Guard in Rust

Source: https://github.com/wvwwvwwv/scalable-concurrent-containers/blob/main/README.md

This example demonstrates how to iterate over entries in an `scc::HashIndex` using the `iter` method, which requires an `ebr::Guard`. It shows how to obtain the guard and use it to create an iterator. The snippet highlights that the references derived from the iterator remain valid as long as the associated `guard` is alive, even if the `HashIndex` itself is dropped.

```Rust
use scc::ebr::Guard;
use scc::HashIndex;

let hashindex: HashIndex<u64, u32> = HashIndex::default();

assert!(hashindex.insert(1, 0).is_ok());

// Existing values can be replaced with a new one.
hashindex.get(&1).unwrap().update(1);

let guard = Guard::new();

// An `Guard` has to be supplied to `iter`.
let mut iter = hashindex.iter(&guard);

// The derived reference can live as long as `guard`.
let entry_ref = iter.next().unwrap();
assert_eq!(iter.next(), None);

drop(hashindex);

// The entry can be read after `hashindex` is dropped.
assert_eq!(entry_ref, (&1, &1));
```

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

### Performing Basic HashMap Operations in Rust

Source: https://github.com/wvwwvwwv/scalable-concurrent-containers/blob/main/README.md

This snippet demonstrates fundamental synchronous and asynchronous operations on an `scc::HashMap`, including inserting new entries, handling key collisions, updating existing entries, reading values, removing entries, and using the `entry` API for conditional insertion. It shows how to create a default HashMap and perform common manipulations.

```Rust
use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

assert!(hashmap.insert(1, 0).is_ok());
assert!(hashmap.insert(1, 1).is_err());
assert_eq!(hashmap.upsert(1, 1).unwrap(), 0);
assert_eq!(hashmap.update(&1, |_, v| { *v = 3; *v }).unwrap(), 3);
assert_eq!(hashmap.read(&1, |_, v| *v).unwrap(), 3);
assert_eq!(hashmap.remove(&1).unwrap(), (1, 3));

hashmap.entry(7).or_insert(17);
assert_eq!(hashmap.read(&7, |_, v| *v).unwrap(), 17);

let future_insert = hashmap.insert_async(2, 1);
let future_remove = hashmap.remove_async(&1);
```

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

### Performing Basic HashSet Operations in Rust

Source: https://github.com/wvwwvwwv/scalable-concurrent-containers/blob/main/README.md

This snippet demonstrates fundamental operations on an `scc::HashSet`, which is a specialized `HashMap` where the value is `()`. It shows how to check for the presence of a key, insert a key, and perform asynchronous insert and remove operations, highlighting the similarities to the `HashMap` API.

```Rust
use scc::HashSet;

let hashset: HashSet<u64> = HashSet::default();

assert!(hashset.read(&1, |_| true).is_none());
assert!(hashset.insert(1).is_ok());
assert!(hashset.read(&1, |_| true).unwrap());

let future_insert = hashset.insert_async(2);
let future_remove = hashset.remove_async(&1);
```

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

### Using Stack Container in Rust

Source: https://github.com/wvwwvwwv/scalable-concurrent-containers/blob/main/README.md

This snippet demonstrates the last-in-first-out (LIFO) behavior of the `Stack` container. It shows pushing multiple elements onto the stack and then popping them, illustrating that the last element pushed is the first one retrieved.

```rust
use scc::Stack;

let stack: Stack<usize> = Stack::default();

stack.push(1);
stack.push(2);
assert_eq!(stack.pop().map(|e| **e), Some(2));
assert_eq!(stack.pop().map(|e| **e), Some(1));
assert!(stack.pop().is_none());
```

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

### Migrating HashMap Upsert Method Rust

Source: https://github.com/wvwwvwwv/scalable-concurrent-containers/blob/main/CHANGELOG.md

This Rust snippet demonstrates how to replace the deprecated `HashMap::upsert` method introduced in version 2.0.0 with the new recommended pattern using `HashMap::entry`, `and_modify`, and `or_insert` for atomic entry operations. It requires the `scc::HashMap` type.

```Rust
use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

// hashmap.upsert(1, || 2, |_, v| *v = 3);
hashmap.entry(1).and_modify(|v| { *v = 3 }).or_insert(2);
```

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

### Using Bag Container in Rust

Source: https://github.com/wvwwvwwv/scalable-concurrent-containers/blob/main/README.md

This snippet shows the basic operations for the `Bag` concurrent container. It demonstrates pushing an element, checking if the bag is empty, popping an element, and confirming that the bag becomes empty again after the last element is removed. `Bag` is an unordered container.

```rust
use scc::Bag;

let bag: Bag<usize> = Bag::default();

bag.push(1);
assert!(!bag.is_empty());
assert_eq!(bag.pop(), Some(1));
assert!(bag.is_empty());
```

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

### Iterating HashMap Entries in Rust

Source: https://github.com/wvwwvwwv/scalable-concurrent-containers/blob/main/README.md

Since `scc::HashMap` does not provide a standard `Iterator`, this snippet demonstrates alternative methods for iterating or processing entries. It shows how to use `retain` to iterate and conditionally modify/remove entries, `any` to check for existence based on a predicate, `first_entry` and `next` for synchronous traversal, and `scan_async`, `first_entry_async`, and `next_async` for asynchronous traversal, highlighting the `Send` property of `OccupiedEntry`.

```Rust
use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

assert!(hashmap.insert(1, 0).is_ok());
assert!(hashmap.insert(2, 1).is_ok());

// Entries can be modified or removed via `retain`.
let mut acc = 0;
hashmap.retain(|k, v_mut| { acc += *k; *v_mut = 2; true });
assert_eq!(acc, 3);
assert_eq!(hashmap.read(&1, |_, v| *v).unwrap(), 2);
assert_eq!(hashmap.read(&2, |_, v| *v).unwrap(), 2);

// `any` returns `true` when an entry satisfying the predicate is found.
assert!(hashmap.insert(3, 2).is_ok());
assert!(hashmap.any(|k, _| *k == 3));

// Multiple entries can be removed through `retain`.
hashmap.retain(|k, v| *k == 1 && *v == 2);

// `hash_map::OccupiedEntry` also can return the next closest occupied entry.
let first_entry = hashmap.first_entry();
assert_eq!(*first_entry.as_ref().unwrap().key(), 1);
let second_entry = first_entry.and_then(|e| e.next());
assert!(second_entry.is_none());

fn is_send<T: Send>(f: &T) -> bool {
    true
}

// Asynchronous iteration over entries using `scan_async`.
let future_scan = hashmap.scan_async(|k, v| println!("{k} {v}"));
assert!(is_send(&future_scan));

// Asynchronous iteration over entries using the `Entry` API.
let future_iter = async {
    let mut iter = hashmap.first_entry_async().await;
    while let Some(entry) = iter {
        // `OccupiedEntry` can be sent across awaits and threads.
        assert!(is_send(&entry));
        assert_eq!(*entry.key(), 1);
        iter = entry.next_async().await;
    }
};
assert!(is_send(&future_iter));
```

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

### Iterating Over TreeIndex Entries in Rust

Source: https://github.com/wvwwvwwv/scalable-concurrent-containers/blob/main/README.md

This snippet demonstrates how to iterate over all entries in a `TreeIndex` using the `iter` method. Iteration is performed without acquiring locks, utilizing an `sdd::Guard` for memory safety. It shows insertion of multiple entries and subsequent sequential access via the iterator.

```rust
use scc::TreeIndex;
use sdd::Guard;

let treeindex: TreeIndex<u64, u32> = TreeIndex::new();

assert!(treeindex.insert(1, 10).is_ok());
assert!(treeindex.insert(2, 11).is_ok());
assert!(treeindex.insert(3, 13).is_ok());

let guard = Guard::new();

// `iter` iterates over entries without acquiring a lock.
let mut iter = treeindex.iter(&guard);
assert_eq!(iter.next().unwrap(), (&1, &10));
assert_eq!(iter.next().unwrap(), (&2, &11));
assert_eq!(iter.next().unwrap(), (&3, &13));
assert!(iter.next().is_none());
```

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

### Migrating HashIndex Modify and Update Methods Rust

Source: https://github.com/wvwwvwwv/scalable-concurrent-containers/blob/main/CHANGELOG.md

This Rust snippet illustrates the migration path for the deprecated `HashIndex::modify` and `HashIndex::update` methods as of version 2.0.0. The new approach involves using `HashIndex::get` to obtain an entry and then calling its `update` method or accessing the contained value mutably using `get_mut`. It depends on the `scc::HashIndex` type.

```Rust
use scc::HashIndex;

let hashindex: HashIndex<u64, u32> = HashIndex::default();
assert!(hashindex.insert(1, 1).is_ok());

// hashindex.modify(&1, |_, v| Some(Some(2)));
if let Some(mut o) = hashindex.get(&1) {
    o.update(2);
};

// unsafe { hashindex.update(&1, |_, v| { *v = 3; true } ); }
if let Some(mut o) = hashindex.get(&1) {
    unsafe { *o.get_mut() = 3; }
};
```
Tokens:
Raw