lockable

lockable is a Rust library offering thread-safe data structures, LockableHashMap, LockableLruCache, and LockPool, in which individual keys can be locked and unlocked independently, even when no entry exists for that key. This makes it possible to synchronize access to an underlying key-value store or to build cache structures on top of one without a single global lock.

Locks can be acquired synchronously or asynchronously (via async/await), support blocking and non-blocking acquisition, and integrate with Tokio. The crate forbids unsafe code and ships with extensive tests and benchmarks.

What You Get

• LockableHashMap for a thread-safe map with independently lockable keys
• LockableLruCache combining LRU eviction with per-key locking
• LockPool for locking arbitrary keys without storing associated values
• Synchronous and asynchronous (async/await) lock acquisition, plus blocking and try-lock variants
• Tokio integration, no-unsafe-code guarantee, and included Criterion benchmarks

Common Use Cases

• Synchronizing concurrent access to entries in an underlying key-value store
• Building cache data structures where only the affected key is locked during updates
• Preventing duplicate concurrent work (e.g. cache stampedes) on a per-key basis

Under The Hood

Architecture - A shared LockableMapImpl (src/lockable_map_impl.rs) backs all public types, parameterized over a MapLike abstraction (src/map_like.rs) so both a HashMap and an lru cache can reuse the same locking machinery. Public wrappers live in src/lockable_hash_map.rs, src/lockable_lru_cache.rs, and src/lockpool.rs, exposing a common Lockable trait (src/lockable_trait.rs); acquired locks are represented by RAII guards in src/guard.rs.

Tech Stack - Rust edition 2024 (MSRV 1.85) built on futures, tokio (sync + time), derive_more for error/display derivation, itertools, and an optional lru dependency behind the default lru feature. Criterion powers the benchmark harness in benches/bench.rs.

Code Quality - The crate forbids unsafe code and carries a large test suite, with tests colocated across the public types plus a dedicated src/tests.rs, and codecov coverage tracking in CI. Utility modules under src/utils/ (stream, time, primary_arc) are individually tested.

API Design - A single Lockable trait unifies the three data structures, and guard-based RAII locking maps naturally to Rust’s ownership model, releasing locks on drop. Sync and async variants share consistent method naming, and thorough docs.rs documentation with examples keeps adoption straightforward.