pulse_map 0.6.3

A CPU cache-line hash table with zero-cost eviction. Every bucket fits in exactly one 64-byte cache line with embedded LFU+LRU eviction metadata.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

# Contributing to PulseMap

Thank you for your interest in contributing to PulseMap! 🎉

## Getting Started

```bash
git clone https://github.com/ddsha441981/pulse_map.git
cd pulse_map
cargo build
cargo test
```

## Development Workflow

### 1. Fork & Branch
```bash
git checkout -b feature/your-feature
```

### 2. Code Standards

- **Format**: Run `cargo fmt` before committing
- **Lint**: Run `cargo clippy -- -D warnings` — zero warnings policy
- **Test**: Run `cargo test` — all tests must pass
- **Docs**: Run `cargo doc --no-deps` — no doc warnings

### 3. Commit Messages

Follow [Conventional Commits](https://www.conventionalcommits.org/):
```
feat: add TTL-based expiration
fix: resolve race condition in concurrent resize
perf: optimize H2 matching with SIMD prefetch
docs: update benchmark tables
```

### 4. Pull Request

- Describe what changed and why
- Reference any related issues
- Ensure CI passes (clippy, fmt, test, doc)

## Architecture

```
Layer 4: sync.rs    → ConcurrentPulseMap (thread-safe, per-bucket locks)
Layer 3: lib.rs     → User API (TypedPulseMap<K,V>, PulseMap, Entry API)
Layer 2: raw.rs     → Hash table logic (insert/get/remove/evict)
Layer 1: core/      → Building blocks (MetaWord, Slot, Bucket, hash)
```

### Key Design Rules

1. **Every bucket = exactly 64 bytes** (1 CPU cache line)
2. **Eviction is zero-cost** — embedded LFU+LRU metadata in MetaWord
3. **No heap allocation in hot path** — inline slots for small KV pairs
4. **Thread safety via `&self`** — no `&mut self` for CRUD, enables `Arc<ConcurrentPulseMap>`

## Testing

```bash
# All tests
cargo test

# Specific feature
cargo test --no-default-features     # no_std
cargo test --features simd           # SIMD (x86_64)

# Benchmarks
cargo bench
```

## Feature Flags

| Flag | Default | Description |
|------|:-------:|-------------|
| `std` | ✅ | Standard library (ConcurrentPulseMap) |
| `simd` | ❌ | SIMD H2 matching (x86_64 only) |

## Reporting Issues

- **Bug**: Include Rust version, OS, and minimal reproduction
- **Performance**: Include benchmark results with `cargo bench`
- **Feature**: Describe the use case, not just the solution

## Code of Conduct

Be respectful, constructive, and inclusive. We follow the [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct).

## License

By contributing, you agree that your contributions will be licensed under MIT OR Apache-2.0.

---

**Questions?** Open an issue or reach out to [@ddsha441981](https://github.com/ddsha441981).