Skip to content

Latest commit

 

History

History
148 lines (111 loc) · 5.17 KB

README.md

File metadata and controls

148 lines (111 loc) · 5.17 KB
Raw

bitbelay

CI: Status License: Apache 2.0 License: MIT

A performance evaluation harness for non-cryptographic hash functions.

Request Feature · Report Bug · ⭐ Consider starring the repo! ⭐

Bitbelay is a framework for testing the performance and desirable characteristics of non-cryptographic hashing functions. The project was given this name because (a) it is concerned with evaluating the characteristics of bits output from hash functions and (b) "belaying" evokes imagery of a (test) harness.

Bitbelay is designed somewhat differently than other popular hash testing frameworks [1]. For example, it does not a ship a single binary that is used to benchmark performance across multiple hash functions. Instead, it (a) is comprised of a family of crates that provide high-quality facilities for testing hash functions and (b) enables hash developers to easily wrap their hash functions in a command line tool for performance testing.

Command line tools are generally written and published containing the facilities for characterizing an individual hash function. When publishing these on crates.io or elsewhere, the convention is to name the crate and/or associated command line tool as bitbelay-[HASHNAME] (e.g., bitbelay-ahash for ahash) so that it can be easily identified.

🎨 Features

  • Advanced hash characterization. Bitbelay's primary goal is to provide facilities for characterizing the performance and quality of non-cryptographic hash functions. As such, it contains an extensive set of tests organized into a collection of purpose-built test suites.
  • Multiple data providers. Bitbelay includes a range of data providers to facilitate the assessment of hash functions against a variety of input data types. This diversity allows for a more comprehensive understanding of hash function performance across different scenarios. Further, custom data providers can be seamlessly integrated into the framework.
  • Drop-in testing for hash function development. Bitbelay aims to ease the process of developing hash functions—especially in Rust! To accomplish this, it includes facilities to easily wrap a hash function as a command-line tool within which a battery of tests can be employed.

📚 Getting Started

You can add bitbelay as a dependency via the Github repository.

cargo add bitbelay

Next, you can use the bitbelay::cli::wrapper() function to quickly wrap a hash function of interest and produce a command-line tool for evaluating it. For this example, we simply pull in Rust's d

use std::hash::RandomState;

pub fn main() -> anyhow::Result<()> {
    bitbelay::cli::wrapper(RandomState::default())
}

Examples

You can also take a look at the examples to get a sense of the various ways you can use the crate.

🖥️ Development

To bootstrap a development environment, please use the following commands.

# Clone the repository
git clone git@github.com:claymcleod/bitbelay.git
cd bitbelay 

# Build the crate in release mode
cargo build --release

# List out the examples
cargo run --release --example

🚧️ Tests

Before submitting any pull requests, please make sure the code passes the following checks.

# Run the project's tests.
cargo test --all-features

# Ensure the project doesn't have any linting warnings.
cargo clippy --all-features

# Ensure the project passes `cargo fmt`.
cargo fmt --check

# Ensure the docs build successfully.
cargo doc

Minumum Supported Rust Version (MSRV)

As bitbelay is pre-1.0, no MSRV is yet asserted.

🤝 Contributing

Contributions, issues and feature requests are welcome! Feel free to check issues page.

📝 License

This project is licensed as either Apache 2.0 or MIT at your discretion.

Copyright © 2024-Present Clay McLeod.