The rust-cuckoofilter repository is a Rust implementation of the cuckoo filter data structure, designed as a practical alternative to Bloom filters for approximate set-membership queries. The cuckoo filter addresses a fundamental limitation of traditional Bloom filters: the inability to delete items. While Bloom filters excel at space efficiency for membership testing, they require significant additional space when deletion capability is needed, such as in counting Bloom filter variants. Cuckoo filters solve this problem by supporting both dynamic insertion and deletion of items while maintaining competitive space efficiency.
The implementation is based on cuckoo hashing principles, where the filter functions as a cuckoo hash table that stores fingerprints of keys rather than the keys themselves. This fingerprint-based approach enables the filter to achieve space efficiency comparable to or better than conventional Bloom filters, particularly for applications requiring low false positive rates below three percent. The repository includes comprehensive documentation available on docs.rs, making it accessible for developers seeking to integrate this data structure into their projects.
A notable feature of this implementation is its C interface, provided through a separate crate called cuckoofilter_cabi. This C binding allows the cuckoo filter to be embedded and used in programming languages beyond Rust, expanding its applicability across different technology stacks. The C interface documentation is available alongside the main Rust documentation, facilitating integration for polyglot development environments.
The implementation makes specific design choices documented in the repository's notes. It uses a static bucket size of four fingerprints and a fingerprint size of one byte, based on the authors' analysis of optimal configuration ratios derived from the original academic paper by Bin Fan, Dave Andersen, and Michael Kaminsky titled "Cuckoo Filter: Better Than Bloom." This paper provides the theoretical foundation and algorithmic details for the implementation.
The repository acknowledges areas for potential improvement. When the filter returns a NotEnoughSpace error, the requested element is added but a random existing element is removed to make room. The developers note this behavior could be enhanced by implementing a single-item eviction cache to preserve the removed item. Additionally, the repository currently lacks high-level language bindings beyond C, though the developers suggest that bindings for languages like Python could be added using tools such as milksnake.
GitGenius activity data indicates this repository maintains connections with major Rust ecosystem projects through overlapping contributors, including the rust-lang/rust repository, astral-sh/uv, and travis-ci/travis-ci. The repository is classified across multiple relevant domains including insertion, hashing algorithms, high performance computing, memory efficiency, and probabilistic data structures, reflecting its position as a specialized but important tool for developers requiring efficient set membership testing with deletion support.
