seqmap/
lib.rs

1//! This crate provides a set of data structures optimized for highly performant concurrent
2//! access with thounds of readers and writers. The basic building block is the [`SeqArray`],
3//! which is in turn used to implement the more complex [`SeqMap`], which is designed to
4//! greatly out-perform `DashMap` and other lock-free concurrent hash map solutions. The main
5//! caveat when using this crate is that your key and value types must implement [`Copy`].
6//!
7//! [`SeqArray`] and data structures that use it as a backing allow for lock-free concurrent
8//! reads to all elements (except during resizing, when a spin-wait strategy is used), and
9//! highly concurrent writes on all elements with minimal contention. Internally each data cell
10//! is protected by a [`seqlock::SeqLock`].
11//!
12//! [`SeqMap`] is a thin veneer over [`SeqArray`] that implements open addressing with linear
13//! probing. It provides a highly concurrent map interface with minimal contention, and
14//! supports concurrent reads and writes with no locks.
15//!
16//! All data structures in this crate use interior mutability and can be safely shared and
17//! passed between threads. They are designed to be used in a highly concurrent environment
18//! where many threads are reading and writing concurrently, and match the performance of their
19//! non-current counterparts in single-threaded scenarios.
20//!
21//! Special care has also been taken to ensure important atomics are placed on isolated cache
22//! lines to avoid false sharing, which can significantly degrade performance in real-world
23//! concurrent environments.
24//!
25//! ## [`SeqMap`] Example
26//! ```
27//! use seqmap::SeqMap;
28//!
29//! let map = SeqMap::<u64, u8>::new();
30//!
31//! map.insert(1, 42);
32//! map.insert(2, 43);
33//!
34//! std::thread::scope(|s| {
35//!    s.spawn(|| {
36//!        assert_eq!(map.get(1), Some(42));
37//!        map.insert(3, 100);
38//!    });
39//!    s.spawn(|| {
40//!       assert_eq!(map.get(2), Some(43));
41//!       map.insert(4, 101);
42//!    });
43//! });
44//!
45//! assert_eq!(map.get(1), Some(42));
46//! assert_eq!(map.get(2), Some(43));
47//! assert_eq!(map.get(3), Some(100));
48//! assert_eq!(map.get(4), Some(101));
49//! ```
50//!
51//! ## [`SeqArray`] Example
52//! ```
53//! use seqmap::SeqArray;
54//!
55//! let arr = SeqArray::<u32>::with_capacity(4);
56//!
57//! arr.set(0, 1);
58//! arr.set(1, 2);
59//!
60//! std::thread::scope(|s| {
61//!     s.spawn(|| {
62//!         assert_eq!(arr.get(0), Ok(1));
63//!         assert_eq!(arr.get(1), Ok(2));
64//!         arr.set(2, 3);
65//!     });
66//!     s.spawn(|| {
67//!         assert_eq!(arr.get(0), Ok(1));
68//!         assert_eq!(arr.get(1), Ok(2));
69//!         arr.set(3, 4);
70//!     });
71//! });
72//!
73//! assert_eq!(arr.get(0), Ok(1));
74//! assert_eq!(arr.get(1), Ok(2));
75//! assert!(
76//!     (arr.get(2) == Ok(3) && arr.get(3) == Ok(4)) ||
77//!     (arr.get(2) == Ok(4) && arr.get(3) == Ok(3))
78//! );
79//! ```
80
81use core::hash::Hash;
82use std::{
83    hash::{DefaultHasher, Hasher},
84    marker::PhantomData,
85};
86
87mod array;
88mod map;
89mod vec;
90
91pub use array::*;
92pub use map::*;
93//pub use vec::*;
94
95// Golden Ratio is optimal
96const GOLDEN_RATIO: f64 = 1.618_033_988_749_895;
seqmap/lib.rs

seqmap/
lib.rs
