papaya

When choosing papaya for your project, consider the following performance characteristics:

• Read-Heavy Workloads: papaya is highly optimized for read-heavy workloads and outperforms many competitors in this category. A core guarantee is that reads never block under any circumstances, ensuring consistent read latency regardless of write concurrency.
• Write-Heavy Workloads: papaya may fall short in update-heavy workloads due to allocator pressure and the overhead of memory reclamation required to maintain lock-free reads. If your workload is primarily write-heavy and does not require lock-free reads, consider an alternative hash-table implementation.
• Latency Distribution: papaya provides more consistent latency distribution compared to implementations like dashmap. This is achieved through incremental resizing and the absence of bucket locks, which helps keep tail latency significantly lower (often by several orders of magnitude).

Note: Benchmarks are workload-specific. Always measure performance using your specific workload before making architectural decisions.

To interact with a papaya::HashMap, you must use a pin. Because the map is concurrent and entries can be removed, papaya uses pinning to ensure that references returned by the map remain valid for the duration of the pin's lifetime.

• A pin acts like a lock guard: it ties the lifetime of any returned references to the guard itself.
• Unlike a standard Mutex lock, pinning is cheap and cannot cause deadlocks.
• Important: Holding a guard prevents the map from performing garbage collection. While pinning is relatively inexpensive, you should avoid holding guards indefinitely. Reuse guards where reasonable to minimize the cost of pinning/unpinning.

use papaya::HashMap;

// Create a map.
let map = HashMap::new();

// Pin the map to get a guard.
let map = map.pin();

// Use the map as normal. References are tied to the lifetime of `map`.
map.insert('A', 1);
assert_eq!(map.get(&'A'), Some(&1));

Because HashSet is concurrent, most operations require a Guard to ensure memory safety and prevent garbage collection of active nodes. There are three primary ways to interact with the set:

1. Manual Guarding: Call .guard() to get a LocalGuard. This is useful for short-lived, synchronous operations. You must pass this guard to methods like .get(), .insert(), or .contains().
2. Pinning (pin): Call .pin() to get a HashSetRef with a LocalGuard. This provides a convenient interface where you don't have to pass the guard to every method call manually.
3. Owned Pinning (pin_owned): Call .pin_owned() to get a HashSetRef with an OwnedGuard. Unlike pin(), this reference implements Send and Sync, making it safe to hold across .await points in async/work-stealing schedulers (e.g., when using iterators in an async task).

// 1. Manual Guarding
let guard = set.guard();
set.insert(1, &guard);
let exists = set.contains(&1, &guard);

// 2. Pinning (Local)
let pinned = set.pin();
pinned.insert(1);
assert!(pinned.contains(&1));

// 3. Owned Pinning (Send/Sync for async)
let owned_pinned = set.pin_owned();
// This can be moved into an async block or held across .await

By default, a pinned map guard (LocalGuard) is not Send because it is tied to the current thread. This prevents you from holding a reference across an .await point in work-stealing schedulers (like Tokio).

To use the map across .await points, use pin_owned() to create an OwnedGuard.

Note: OwnedGuard is more expensive to create than a regular guard. If you only need a value briefly, it is more efficient to drop the guard, perform the async operation, and then re-pin the map to fetch the value again.

use std::sync::Arc;
use papaya::HashMap;

async fn run(map: Arc<HashMap<i32, String>>) {
    tokio::spawn(async move {
        // Use pin_owned() to allow the guard to be Send
        let map = map.pin_owned();

        // The reference can now be held across this .await
        let value = map.get(&37);
        tokio::fs::write("db.txt", format!("{value:?}")).await;
        println!("{value:?}");
    });
}

When returning references to data contained within a HashMap that is part of a larger struct, you cannot return a reference tied to a temporary pin. Instead, you should use the Guard trait to allow the caller to provide the lifetime.

To implement this:

1. Provide a method that returns an object implementing Guard (using map.guard()).
2. Use a generic lifetime 'guard in your methods that accepts &'guard impl Guard to tie the returned reference to the caller's guard.

use papaya::Guard;

pub struct Metrics {
    map: papaya::HashMap<String, Vec<u64>>
}

impl Metrics {
    // Returns a guard that the caller can use to manage lifetimes
    pub fn guard(&self) -> impl Guard + '_ {
        self.map.guard()
    }

    // The returned reference is tied to the lifetime of the provided guard
    pub fn get<'guard>(&self, name: &str, guard: &'guard impl Guard) -> Option<&'guard [u64]> {
        self.map.get(name, guard)?.as_slice()
    }
}