init

README.md

@@ -0,0 +1,62 @@
+# 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.
+
+## 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.
+
+## Benchmark Results
+
+Done with 100 million iterations on a quiet AMD Ryzen AI 5 340.
+
+### Throughput
+
+![Throughput Results](throughput_results.png)
+
+### Speedup
+
+![Speedup Results](speedup_results.png)