lockmap/lib.rs
1//! A high-performance, thread-safe HashMap and LRU cache with fine-grained per-key locking.
2//!
3//! # Overview
4//!
5//! This crate provides two concurrent map implementations:
6//!
7//! - [`LockMap`]: A thread-safe HashMap with per-key level locking
8//! - [`LruLockMap`]: A thread-safe LRU cache with per-key locking and automatic eviction
9//!
10//! Both data structures use internal sharding for high concurrency and allow you to
11//! hold an exclusive lock on a specific key for complex atomic operations, minimizing
12//! contention across different keys.
13//!
14//! # Features
15//!
16//! - **Per-key locking**: Acquire exclusive locks for specific keys; operations on different keys run in parallel
17//! - **Sharding architecture**: Internal sharding reduces contention on the map structure itself
18//! - **Single hash computation**: Key and pre-computed hash stored together; each operation hashes once
19//! - **No key duplication**: Uses [`hashbrown::HashTable`] so each key is stored only once
20//! - **Deadlock prevention**: `LockMap` provides [`batch_lock`](LockMap::batch_lock) for safe multi-key locking
21//! - **LRU eviction**: `LruLockMap` automatically evicts least recently used entries when capacity is exceeded
22//! - **Non-blocking eviction**: In-use entries are skipped during eviction; traversal continues to the next candidate
23//!
24//! # Examples
25//!
26//! ## LockMap
27//!
28//! ```
29//! use lockmap::LockMap;
30//!
31//! let map = LockMap::<String, u32>::new();
32//!
33//! map.insert("key".to_string(), 42);
34//! assert_eq!(map.get("key"), Some(42));
35//!
36//! {
37//! let mut entry = map.entry("key2".to_string());
38//! entry.insert(123);
39//! }
40//!
41//! assert_eq!(map.remove("key"), Some(42));
42//! ```
43//!
44//! ## LruLockMap
45//!
46//! ```
47//! use lockmap::LruLockMap;
48//!
49//! let cache = LruLockMap::<String, u32>::new(1000);
50//!
51//! cache.insert("key".to_string(), 42);
52//! assert_eq!(cache.get("key"), Some(42));
53//!
54//! {
55//! let mut entry = cache.entry("key2".to_string());
56//! entry.insert(123);
57//! }
58//!
59//! assert_eq!(cache.remove("key"), Some(42));
60//! ```
61
62#[doc = include_str!("../README.md")]
63mod lockmap;
64mod lru_lockmap;
65
66pub use lockmap::{Entry, LockMap};
67pub use lru_lockmap::{LruEntry, LruLockMap};