CHB (Colony Hash Bucket) is a lightweight on-disk hash table designed for simplicity, predictability, and fast key-value lookups. Data is organized into a fixed-size bucket directory that maps hash values to chains of records stored in a compact append-only area.
Each record contains a pointer to the next record in the chain, a key-length field with deletion flag support, and a fixed-size payload area. Bucket count and record size are configurable at file creation time, allowing CHB to be tuned for different workloads while preserving a simple and deterministic layout.
The format is page-oriented (4 KiB aligned), easy to inspect, recover, and implement, requiring no complex trees, transactions, or variable-length record management. Deleted records can be recycled within their bucket chains, reducing fragmentation without introducing free-list complexity.
CHB is ideal for caches, kv stores, indexes where low implementation complexity is more important than full database features.
Features
- Persistent on-disk hash table storage
- Fixed-size records for predictable performance
- Configurable bucket count (MUL) and record size (SZE)
- 100% PHP
- Fast O(1) average key lookups
- Separate bucket directory and data area
- Collision handling through record chaining
- No external dependencies
- Logical deletion support with recycle of deleted records
- Concurrent access with file locking
