]>
Commit | Line | Data |
---|---|---|
0731742a XL |
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 | |
15 | extern crate crc32fast; | |
16 | ||
17 | use crc32fast::Hasher; | |
18 | ||
19 | let mut hasher = Hasher::new(); | |
20 | hasher.update(b"foo bar baz"); | |
21 | let checksum = hasher.finalize(); | |
22 | ``` | |
23 | ||
24 | ## Performance | |
25 | ||
26 | This 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 | |
3dfed10e | 30 | - An optimized implementation for `aarch64` using `crc32` instructions |
0731742a XL |
31 | |
32 | Calling the `Hasher::new` constructor at runtime will perform a feature detection to select the most | |
33 | optimal 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 | ||
43 | Due to the use of SIMD intrinsics for the optimized implementations, this crate contains some amount of `unsafe` code. | |
44 | ||
45 | 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. | |
46 | ||
47 | On top of that, every commit is tested using an address sanitizer in CI to catch any out of bounds memory accesses. | |
48 | ||
fc512014 | 49 | 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. |
0731742a | 50 | |
3dfed10e XL |
51 | ## Available feature flags |
52 | ||
53 | ### `std` (default: enabled) | |
54 | ||
55 | 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. | |
56 | ||
57 | Note: 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 | ||
61 | This feature flag enables unstable features that are only available on the `nightly` channel. Keep in mind that when enabling this feature flag, you | |
62 | might experience breaking changes when updating compiler versions. | |
63 | ||
64 | Currently, enabling this feature flag will make the optimized `aarch64` implementation available. | |
65 | ||
0731742a XL |
66 | ## License |
67 | ||
68 | This 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 | ||
75 | at your option. | |
76 | ||
77 | ### Contribution | |
78 | ||
79 | Unless you explicitly state otherwise, any contribution intentionally submitted | |
80 | for inclusion in this project by you, as defined in the Apache-2.0 license, | |
81 | shall be dual licensed as above, without any additional terms or conditions. |