third_party/rust/crc32fast/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 ### 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.