papaya

Papaya is a concurrent hash-table for Rust that delivers extremely high-throughput, low-latency reads for workloads where reads outnumber writes. It exposes an ergonomic lock-free API built around cheap pinning instead of lock guards, so it hands out direct references to values without wrapper types and can never deadlock.

Beyond the standard get/insert/remove surface, Papaya provides powerful atomic operations (update, update_or_insert, compute) as a concurrency-safe replacement for the standard entry API, seamless use across async await points via owned guards, and incremental resizing for predictable latency. Memory reclamation is handled automatically by the seize garbage collector.

What You Get

• A lock-free concurrent HashMap and HashSet that hand out direct references to stored values without wrapper types.
• Atomic entry-style operations (update, update_or_insert, get_or_insert, compute) for race-free read-modify-write logic.
• Owned guards (pin_owned) that stay valid across async await points for use in Tokio and other work-stealing runtimes.
• A builder API to configure capacity, custom hashers, resize mode (incremental or blocking), and the seize collector.
• Automatic memory reclamation powered by the seize garbage collector, with incremental resizing for predictable latency.

Common Use Cases

• In-memory caches and shared lookup tables read concurrently from many threads.
• Metrics, counters, and registries accumulated across worker threads in a server.
• Shared state in async services where map references must survive across await points.

Under The Hood

Architecture - The public surface in src/map.rs (HashMap, HashMapBuilder, HashMapRef) and src/set.rs is a thin, safe wrapper over a lock-free hash-table implemented in src/raw/mod.rs. The root table is an AtomicPtr<RawTable> of tagged entry pointers; every operation runs under a seize guard obtained by pinning, which returns direct references tied to the guard’s lifetime. Resizing is coordinated through a State struct that tracks the next table and copied-entry count, supporting both incremental and blocking resize modes via the ResizeMode enum.

Tech Stack - Pure Rust (edition 2021, MSRV 1.72), single crate published to crates.io. Runtime dependencies are minimal: seize for epoch-free memory reclamation and equivalent for flexible key lookup, plus optional serde behind a feature flag. Dev-dependencies (criterion, dashmap, tokio, hdrhistogram) support benchmarking and async tests. The src/raw/utils module carries hand-rolled primitives — a striped counter, parker, stack, and tagged-pointer helpers — including polyfills for APIs stabilized after the MSRV.

Code Quality - Testing is thorough: roughly 3,100 lines across tests/ covering basic map/set behavior, a cuckoo-style test, and a large stress suite, complemented by a fuzz/ harness and dedicated papaya_stress/papaya_asan cfg lints. The test profile inherits release with debug-assertions on. Code is clearly organized with a strict public/internal split and extensively documented invariants.

API Design - The pinning model is the standout ergonomic choice: map.pin() yields a HashMapRef usable almost identically to std::collections::HashMap, while pin_owned() provides Send-able guards for async contexts. The atomic operations (update, update_or_insert, compute, get_or_insert) give a race-free alternative to the standard entry API, and the crate-level docs are exceptionally detailed with runnable examples for usage, consistency, atomics, and async.