# assembly-hashmap
Single-threaded `u64 → u64` hashmap. Table operations run in x86-64 assembly
(SwissTable / SIMD control bytes). Growth, allocation, and migration stay in
Rust. On non-x86-64 targets the crate falls back to a C reference of the same
algorithm.
```toml
[dependencies]
assembly-hashmap = "0.1"
```
A C compiler (`cc` / `clang`) is required at build time.
## Use
```rust
use assembly_hashmap::AssemblyHashMap;
fn main() {
let mut map = AssemblyHashMap::new();
map.put(1, 10);
assert_eq!(map.get(1), Some(10));
assert_eq!(map.remove(1), Some(10));
}
```
See `examples/basic.rs` for the rest of the API (`put_if_absent`, `get_or_insert`,
`replace`, `iter`, `reserve`).
The map is `!Send` / `!Sync`. Operations match `std::collections::HashMap`
for `u64` keys except that the hasher is fixed (FxHash-style multiply) and
the table is not concurrent.
## Examples
```bash
cargo run --example basic
```
## Tests
```bash
cargo test
```
On a non-x86-64 host this tests the C fallback. To exercise `native/hashmap.S`:
```bash
make rust-docker-test
```
## Benchmarks
Replay the same put/get stream against this map and `std::collections::HashMap`:
```bash
cargo run --release --example bench
```
Meaningful numbers need native x86-64. Override workload size:
```bash
HM_BENCH_KEYS=1048576 \
HM_BENCH_OPS=16777216 \
HM_BENCH_ROUNDS=10 \
cargo run --release --example bench
```
| `HM_BENCH_KEYS` | `1 << 18` | insertion key space |
| `HM_BENCH_OPS` | `1 << 21` | operations in the timed stream |
| `HM_BENCH_ROUNDS` | `5` | timed repeats; best time is reported |
The example first checks that both maps produce identical results, then times
each independently. The printed backend line is `x86-64 hashmap.S` when the
assembly path is linked.