README.md
1# crc32fast [![Build Status][travis-img]][travis] [![Crates.io][crates-img]][crates] [![Documentation][docs-img]][docs]
2
3[travis-img]: https://travis-ci.com/srijs/rust-crc32fast.svg?branch=master
4[travis]: https://travis-ci.com/srijs/rust-crc32fast
5[crates-img]: https://img.shields.io/crates/v/crc32fast.svg
6[crates]: https://crates.io/crates/crc32fast
7[docs-img]: https://docs.rs/crc32fast/badge.svg
8[docs]: https://docs.rs/crc32fast
9
10_Fast, SIMD-accelerated CRC32 (IEEE) checksum computation_
11
12## Usage
13
14```rust
15extern crate crc32fast;
16
17use crc32fast::Hasher;
18
19let mut hasher = Hasher::new();
20hasher.update(b"foo bar baz");
21let checksum = hasher.finalize();
22```
23
24## Performance
25
26This crate contains multiple CRC32 implementations:
27
28- A fast baseline implementation which processes up to 16 bytes per iteration
29- An optimized implementation for modern `x86` using `sse` and `pclmulqdq` instructions
30- An optimized implementation for `aarch64` using `crc32` instructions
31
32Calling the `Hasher::new` constructor at runtime will perform a feature detection to select the most
33optimal implementation for the current CPU feature set.
34
35| crate | version | variant | ns/iter | MB/s |
36|-------------------------------------|---------|-----------|---------|------|
37| [crc](https://crates.io/crates/crc) | 1.8.1 | n/a | 4,926 | 207 |
38| crc32fast (this crate) | 1.0.0 | baseline | 683 | 1499 |
39| crc32fast (this crate) | 1.0.0 | pclmulqdq | 140 | 7314 |
40
41## Memory Safety
42
43Due to the use of SIMD intrinsics for the optimized implementations, this crate contains some amount of `unsafe` code.
44
45In order to ensure memory safety, the relevant code has been fuzz tested using [afl.rs](https://github.com/rust-fuzz/afl.rs) with millions of iterations in both `debug` and `release` build settings. You can inspect the test setup in the `fuzz` sub-directory, which also has instructions on how to run the tests yourself.
46
47On top of that, every commit is tested using an address sanitizer in CI to catch any out of bounds memory accesses.
48
49Even though neither fuzzing nor sanitization has revealed any safety bugs yet, please don't hesitate to file an issue if you run into any crashes or other unexpected behaviour.
50
51## Available feature flags
52
53### `std` (default: enabled)
54
55This library supports being built without the Rust `std` library, which is useful for low-level use-cases such as embedded where no operating system is available. To build the crate in a `no_std` context, disable the default `std` feature.
56
57Note: Because runtime CPU feature detection requires OS support, the specialized SIMD implementations will be unavailable when the `std` feature is disabled.
58
59### `nightly` (default: disabled)
60
61This feature flag enables unstable features that are only available on the `nightly` channel. Keep in mind that when enabling this feature flag, you
62might experience breaking changes when updating compiler versions.
63
64Currently, enabling this feature flag will make the optimized `aarch64` implementation available.
65
66## License
67
68This project is licensed under either of
69
70 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
71 http://www.apache.org/licenses/LICENSE-2.0)
72 * MIT license ([LICENSE-MIT](LICENSE-MIT) or
73 http://opensource.org/licenses/MIT)
74
75at your option.
76
77### Contribution
78
79Unless you explicitly state otherwise, any contribution intentionally submitted
80for inclusion in this project by you, as defined in the Apache-2.0 license,
81shall be dual licensed as above, without any additional terms or conditions.
82
