# HashMapConcurrent

A thread-safe, fixed-capacity, open-addressing hash map for Zig.

This implementation combines *Robin Hood hashing* (to minimize probe lengths) with *Sequence
Locking* (to provide wait-free-like read performance) and *Shard-Level Locking* for writers.
Deletions use *Backward-Shift* to maintain table compactness without the performance degradation
of tombstones.

<img src="benchmark_results.png" alt="Benchmark Results" width="75%">

## Quick Start

```zig
const std = @import("std");
const HashMap = @import("hashmap_concurrent.zig").AutoHashMapConcurrent;

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    const allocator = gpa.allocator();

    // capacity must be a power of two.
    // num_shards balances writer contention vs reader retry probability.
    var map = try HashMap(u64, u64).init(allocator, 1024, 64);
    defer map.deinit(allocator);

    map.put(42, 1337);
    const val = map.get(42);
    std.debug.print("Value: {d}\n", .{val});
}
```

## Iteration

There are two ways to iterate over entries, depending on your consistency requirements:

`lockingIterator()`: Uses *Lock Coupling* to prevent elements from being missed or seen twice if they
are moved across shard boundaries during iteration. Due to the locking you must call `it.deinit()`
if you break or return from the loop early to release the held shard lock.

`approximateIterator()`: Optimistic and approximate because it just uses *Sequence Locks*. It may
miss entries or see the same entry twice if concurrent writers move elements. It's Lock-free and
safe to use on const references. Safe to break early without cleanup.

## Usage & Safety

For a detailed explanation of the concurrency model, deadlock safety, and memory reclamation, please
refer to the documentation at the top of `hashmap_concurrent.zig`.

## License

BSD 3-Clause. See `hashmap_concurrent.zig` and `LICENSE` for the full text.