| 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 |
### Simple usage |
| 15 |
|
| 16 |
For simple use-cases, you can call the `hash` convenience function to |
| 17 |
directly compute the CRC32 checksum for a given byte slice: |
| 18 |
|
| 19 |
```rust |
| 20 |
let checksum = crc32fast::hash(b"foo bar baz"); |
| 21 |
``` |
| 22 |
|
| 23 |
### Advanced usage |
| 24 |
|
| 25 |
For use-cases that require more flexibility or performance, for example when |
| 26 |
processing large amounts of data, you can create and manipulate a `Hasher`: |
| 27 |
|
| 28 |
```rust |
| 29 |
use crc32fast::Hasher; |
| 30 |
|
| 31 |
let mut hasher = Hasher::new(); |
| 32 |
hasher.update(b"foo bar baz"); |
| 33 |
let checksum = hasher.finalize(); |
| 34 |
``` |
| 35 |
|
| 36 |
## Performance |
| 37 |
|
| 38 |
This crate contains multiple CRC32 implementations: |
| 39 |
|
| 40 |
- A fast baseline implementation which processes up to 16 bytes per iteration |
| 41 |
- An optimized implementation for modern `x86` using `sse` and `pclmulqdq` instructions |
| 42 |
- An optimized implementation for `aarch64` using `crc32` instructions |
| 43 |
|
| 44 |
Calling the `Hasher::new` constructor at runtime will perform a feature detection to select the most |
| 45 |
optimal implementation for the current CPU feature set. |
| 46 |
|
| 47 |
| crate | version | variant | ns/iter | MB/s | |
| 48 |
| ----------------------------------- | ------- | --------- | ------- | ---- | |
| 49 |
| [crc](https://crates.io/crates/crc) | 1.8.1 | n/a | 4,926 | 207 | |
| 50 |
| crc32fast (this crate) | 1.0.0 | baseline | 683 | 1499 | |
| 51 |
| crc32fast (this crate) | 1.0.0 | pclmulqdq | 140 | 7314 | |
| 52 |
|
| 53 |
## Memory Safety |
| 54 |
|
| 55 |
Due to the use of SIMD intrinsics for the optimized implementations, this crate contains some amount of `unsafe` code. |
| 56 |
|
| 57 |
In 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. |
| 58 |
|
| 59 |
On top of that, every commit is tested using an address sanitizer in CI to catch any out of bounds memory accesses. |
| 60 |
|
| 61 |
Even 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. |
| 62 |
|
| 63 |
## Available feature flags |
| 64 |
|
| 65 |
### `std` (default: enabled) |
| 66 |
|
| 67 |
This 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. |
| 68 |
|
| 69 |
Note: Because runtime CPU feature detection requires OS support, the specialized SIMD implementations will be unavailable when the `std` feature is disabled. |
| 70 |
|
| 71 |
### `nightly` (default: disabled) |
| 72 |
|
| 73 |
This feature flag enables unstable features that are only available on the `nightly` channel. Keep in mind that when enabling this feature flag, you |
| 74 |
might experience breaking changes when updating compiler versions. |
| 75 |
|
| 76 |
Currently, enabling this feature flag will make the optimized `aarch64` implementation available. |
| 77 |
|
| 78 |
## License |
| 79 |
|
| 80 |
This project is licensed under either of |
| 81 |
|
| 82 |
- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or |
| 83 |
http://www.apache.org/licenses/LICENSE-2.0) |
| 84 |
- MIT license ([LICENSE-MIT](LICENSE-MIT) or |
| 85 |
http://opensource.org/licenses/MIT) |
| 86 |
|
| 87 |
at your option. |
| 88 |
|
| 89 |
### Contribution |
| 90 |
|
| 91 |
Unless you explicitly state otherwise, any contribution intentionally submitted |
| 92 |
for inclusion in this project by you, as defined in the Apache-2.0 license, |
| 93 |
shall be dual licensed as above, without any additional terms or conditions. |