assembly-hashmap 0.1.0

A single-threaded u64→u64 hashmap with x86-64 assembly operations and Rust-side growth.
Documentation
# 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
```

| Variable | Default | Meaning |
|---|---|---|
| `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.