A collection of high performance containers and utilities for concurrent and asynchronous programming.
HashMap is a concurrent hash map that is targeted at highly concurrent write-heavy workloads. It uses EBR for its hash table memory management in order to implement non-blocking resizing and fine-granular locking without static data sharding; it is not a lock-free data structure, and each access to a single key is serialized by a bucket-level mutex.
A unique key can be inserted along with its corresponding value. The inserted entry can be updated, read, and removed synchronously or asynchronously.
```rust use scc::HashMap;
let hashmap: HashMap
assert!(hashmap.insert(1, 0).isok()); asserteq!(hashmap.update(&1, |v| { *v = 2; *v }).unwrap(), 2); asserteq!(hashmap.read(&1, |, v| *v).unwrap(), 2); assert_eq!(hashmap.remove(&1).unwrap(), (1, 2));
let futureinsert = hashmap.insertasync(2, 1); let futureremove = hashmap.removeasync(&1); ```
The upsert method inserts a new entry if the key does not exist, or updates the value field.
```rust use scc::HashMap;
let hashmap: HashMap
hashmap.upsert(1, || 2, |, v| *v = 2); asserteq!(hashmap.read(&1, |, v| *v).unwrap(), 2); hashmap.upsert(1, || 2, |, v| *v = 3); asserteq!(hashmap.read(&1, |, v| *v).unwrap(), 3);
let futureupsert = hashmap.upsertasync(2, || 1, |_, v| *v = 3); ```
There is no method to confine the lifetime of references derived from an Iterator to the Iterator, and it is illegal to let them live as long as the HashMap. Therefore Iterator is not implemented, instead, it provides a number of methods to iterate over entries: for_each, for_each_async, scan, scan_async, retain, and retain_async.
```rust use scc::HashMap;
let hashmap: HashMap
assert!(hashmap.insert(1, 0).isok()); assert!(hashmap.insert(2, 1).isok());
// Inside for_each, an ebr::Barrier protects the entry array.
let mut acc = 0;
hashmap.foreach(|k, vmut| { acc += *k; *vmut = 2; });
asserteq!(acc, 3);
// for_each allows entry modification.
asserteq!(hashmap.read(&1, |, v| *v).unwrap(), 2);
asserteq!(hashmap.read(&2, |, v| *v).unwrap(), 2);
assert!(hashmap.insert(3, 2).is_ok());
// retain enables entry removal.
assert_eq!(hashmap.retain(|k, v| *k == 1 && *v == 0), (1, 2));
// Asynchronous iteration over entries using scan_async and for_each_async.
let futurescan = hashmap.scanasync(|k, v| println!("{k} {v}"));
let futureforeach = hashmap.foreachasync(|k, vmut| { *vmut = *k; });
```
HashSet is a version of HashMap where the value type is ().
All the HashSet methods identical to that of HashMap except that they do not receive a value argument.
```rust use scc::HashSet;
let hashset: HashSet
assert!(hashset.read(&1, || true).isnone()); assert!(hashset.insert(1).isok()); assert!(hashset.read(&1, || true).unwrap());
let futureinsert = hashset.insertasync(2); let futureremove = hashset.removeasync(&1); ```
HashIndex is a read-optimized version of HashMap. It applies EBR to its entry management as well, enabling it to perform read operations without blocking or being blocked.
Its read method is completely lock-free and does not modify any shared data.
```rust use scc::HashIndex;
let hashindex: HashIndex
assert!(hashindex.insert(1, 0).isok()); asserteq!(hashindex.read(&1, |_, v| *v).unwrap(), 0);
let futureinsert = hashindex.insertasync(2, 1); let futureremove = hashindex.removeifasync(&1, || true); ```
An Iterator is implemented for HashIndex, because any derived references can survive as long as the associated ebr::Barrier lives.
```rust use scc::ebr::Barrier; use scc::HashIndex;
let hashindex: HashIndex
assert!(hashindex.insert(1, 0).is_ok());
let barrier = Barrier::new();
// An ebr::Barrier has to be supplied to iter.
let mut iter = hashindex.iter(&barrier);
// The derived reference can live as long as barrier.
let entryref = iter.next().unwrap();
asserteq!(iter.next(), None);
drop(hashindex);
// The entry can be read after hashindex is dropped.
asserteq!(entryref, (&1, &0));
```
TreeIndex is a B+ tree variant optimized for read operations. The ebr module enables it to implement lock-free read and scan methods.
Key-value pairs can be inserted, read, and removed.
```rust use scc::TreeIndex;
let treeindex: TreeIndex
assert!(treeindex.insert(1, 2).is_ok());
// read is lock-free.
asserteq!(treeindex.read(&1, |, v| *v).unwrap(), 2);
assert!(treeindex.remove(&1));
let futureinsert = treeindex.insertasync(2, 3); let futureremove = treeindex.removeif_async(&1, |v| *v == 2); ```
Key-value pairs can be scanned.
```rust use scc::ebr::Barrier; use scc::TreeIndex;
let treeindex: TreeIndex
assert!(treeindex.insert(1, 10).isok()); assert!(treeindex.insert(2, 11).isok()); assert!(treeindex.insert(3, 13).is_ok());
let barrier = Barrier::new();
// visitor iterates over entries without acquiring a lock.
let mut visitor = treeindex.iter(&barrier);
asserteq!(visitor.next().unwrap(), (&1, &10));
asserteq!(visitor.next().unwrap(), (&2, &11));
asserteq!(visitor.next().unwrap(), (&3, &13));
assert!(visitor.next().isnone());
```
Key-value pairs in a specific range can be scanned.
```rust use scc::ebr::Barrier; use scc::TreeIndex;
let treeindex: TreeIndex
for i in 0..10 { assert!(treeindex.insert(i, 10).is_ok()); }
let barrier = Barrier::new();
asserteq!(treeindex.range(1..1, &barrier).count(), 0); asserteq!(treeindex.range(4..8, &barrier).count(), 4); assert_eq!(treeindex.range(4..=8, &barrier).count(), 5); ```
Bag is a concurrent lock-free unordered container. Bag is completely opaque, disallowing access to contained instances until they are popped. Bag is especially efficient if the number of contained instances can be maintained under size_of::<usize> * 4.
```rust use scc::Bag;
let bag: Bag
bag.push(1); assert!(!bag.isempty()); asserteq!(bag.pop(), Some(1)); assert!(bag.is_empty()); ```
Queue is an EBR backed concurrent lock-free first-in-first-out container.
```rust use scc::Queue;
let queue: Queue
queue.push(1); assert!(queue.pushif(2, |e| e.mapor(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)); asserteq!(queue.pop().map(|e| **e), Some(2)); assert!(queue.pop().isnone()); ```
Stack is an EBR backed concurrent lock-free last-in-first-out container.
```rust use scc::Stack;
let stack: Stack
stack.push(1); stack.push(2); asserteq!(stack.pop().map(|e| **e), Some(2)); asserteq!(stack.pop().map(|e| **e), Some(1)); assert!(stack.pop().is_none()); ```
The ebr module implements epoch-based reclamation and various types of auxiliary data structures to make use of it safely. Its epoch-based reclamation algorithm is similar to that implemented in crossbeam_epoch, however users may find it easier to use as the lifetime of an instance is safely managed. For instance, ebr::AtomicArc and ebr::Arc hold a strong reference to the underlying instance, and the instance is automatically passed to the garbage collector when the reference count drops to zero.
The ebr module can be used without an unsafe block.
```rust use scc::ebr::{suspend, Arc, AtomicArc, Barrier, Ptr, Tag};
use std::sync::atomic::Ordering::Relaxed;
// atomic_arc holds a strong reference to 17.
let atomic_arc: AtomicArc
// barrier prevents the garbage collector from dropping reachable instances.
let barrier: Barrier = Barrier::new();
// ptr cannot outlive barrier.
let mut ptr: Ptr
// atomic_arc can be tagged.
atomicarc.updatetag_if(Tag::First, |t| t == Tag::None, Relaxed);
// ptr is not tagged, so CAS fails.
assert!(atomicarc.compareexchange(
ptr,
(Some(Arc::new(18)), Tag::First),
Relaxed,
Relaxed,
&barrier).is_err());
// ptr can be tagged.
ptr.set_tag(Tag::First);
// The return value of CAS is a handle to the instance that atomic_arc previously owned.
let prev: Arc
// 17 will be garbage-collected later.
drop(prev);
// ebr::AtomicArc can be converted into ebr::Arc.
let arc: Arc
// 18 will be garbage-collected later.
drop(arc);
// 17 is still valid as barrier keeps the garbage collector from dropping it.
asserteq!(*ptr.asref().unwrap(), 17);
// Execution of a closure can be deferred until all the current readers are gone. barrier.defer_execute(|| println!("deferred")); drop(barrier);
// The closure will be repeatedly invoked until it returns true.
let barrier = Barrier::new();
let mut data = 3;
barrier.deferincrementalexecute(move || {
if data == 0 {
return true;
}
data -= 1;
false
});
drop(barrier);
// If the thread is expected to lie dormant for a while, call suspend() to allow other threads
// to reclaim its own retired instances.
suspend();
```
LinkedList is a type trait that implements lock-free concurrent singly linked list operations, backed by EBR. It additionally provides support for marking an entry of a linked list to denote a user-defined state.
```rust use scc::ebr::{Arc, AtomicArc, Barrier}; use scc::LinkedList;
use std::sync::atomic::Ordering::Relaxed;
struct L(AtomicArc
let barrier = Barrier::new();
let head: L = L::default();
let tail: Arc
// A new entry is pushed. assert!(head.pushback(tail.clone(), false, Relaxed, &barrier).isok()); 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 nextptr = head.nextptr(Relaxed, &barrier);
asserteq!(nextptr.as_ref().unwrap().1, 1);
// Once tail is deleted, it becomes invisible.
tail.deleteself(Relaxed);
assert!(head.nextptr(Relaxed, &barrier).is_null());
```
Comparison with DashMap.