Update docs and benchmarks for v0.1.2 release (#42)

Author: hkratz

Cargo.toml

@@ -29,5 +29,7 @@ aarch64_neon = []
 hints = []
 
 [package.metadata.docs.rs]
-features = ["public_imp"]
+all-features = true
 rustdoc-args = ["--cfg", "docsrs"]
+default-target = "x86_64-unknown-linux-gnu"
+targets = ["aarch64-unknown-linux-gnu"]

README.md

@@ -2,43 +2,49 @@
 [![crates.io](https://img.shields.io/crates/v/simdutf8.svg)](https://crates.io/crates/simdutf8)
 [![docs.rs](https://docs.rs/simdutf8/badge.svg)](https://docs.rs/simdutf8)
 
-# simdutf8 – High-speed UTF-8 validation for Rust
+# simdutf8 – High-speed UTF-8 validation
 
 Blazingly fast API-compatible UTF-8 validation for Rust using SIMD extensions, based on the implementation from
-[simdjson](https://github.com/simdjson/simdjson). Originally ported to Rust by the developers of [simd-json.rs](https://simd-json.rs).
+[simdjson](https://github.com/simdjson/simdjson). Originally ported to Rust by the developers of [simd-json.rs](https://simd-json.rs), but now heavily improved.
 
-## Disclaimer
-This software should not (yet) be used in production, though it has been tested with sample data as well as
-fuzzing and there are no known bugs.
+## Status
+This library has been thoroughly tested with sample data as well as fuzzing and there are no known bugs.
 
 ## Features
 * `basic` API for the fastest validation, optimized for valid UTF-8
 * `compat` API as a fully compatible replacement for `std::str::from_utf8()`
-* Up to 22 times faster than the std library on non-ASCII, up to three times faster on ASCII
-* As fast as or faster than the original simdjson implementation
-* Supports AVX 2 and SSE 4.2 implementations on x86 and x86-64. ARMv7 and ARMv8 neon support is planned
-* Selects the fastest implementation at runtime based on CPU support
+* Supports AVX 2 and SSE 4.2 implementations on x86 and x86-64
+* 🆕 ARM64 (Aarch64) SIMD is supported with Rust nightly (use feature `aarch64_neon`)
+* x86-64: Up to 23 times faster than the std library on valid non-ASCII, up to four times faster on ASCII
+* aarch64: Up to eleven times faster than the std library on valid non-ASCII, up to four times faster on ASCII (Apple Silicon)
+* Faster than the original simdjson implementation
+* Selects the fastest implementation at runtime based on CPU support (on x86)
+* Falls back to the excellent std implementation if SIMD extensions are not supported
 * Written in pure Rust
 * No dependencies
 * No-std support
-* Falls back to the excellent std implementation if SIMD extensions are not supported
 
 ## Quick start
 Add the dependency to your Cargo.toml file:
 ```toml
 [dependencies]
-simdutf8 = { version = "0.1.1" }
+simdutf8 = { version = "0.1.2" }
+```
+or on ARM64 with Rust Nightly:
+```toml
+[dependencies]
+simdutf8 = { version = "0.1.2", features = ["aarch64_neon"] }
 ```
 
-Use `simdutf8::basic::from_utf8` as a drop-in replacement for `std::str::from_utf8()`.
+Use `simdutf8::basic::from_utf8()` as a drop-in replacement for `std::str::from_utf8()`.
 
 ```rust
 use simdutf8::basic::from_utf8;
 
 println!("{}", from_utf8(b"I \xE2\x9D\xA4\xEF\xB8\x8F UTF-8!").unwrap());
 ```
 
-If you need detailed information on validation failures, use `simdutf8::compat::from_utf8`
+If you need detailed information on validation failures, use `simdutf8::compat::from_utf8()`
 instead.
 
 ```rust
@@ -57,16 +63,18 @@ for errors after processing the whole byte sequence and does not provide detaile
 is not valid UTF-8. `simdutf8::basic::Utf8Error` is a zero-sized error struct.
 
 ### Compat flavor
-The `compat` flavor is fully API-compatible with `std::str::from_utf8`. In particular, `simdutf8::compat::from_utf8()`
+The `compat` flavor is fully API-compatible with `std::str::from_utf8()`. In particular, `simdutf8::compat::from_utf8()`
 returns a `simdutf8::compat::Utf8Error`, which has `valid_up_to()` and `error_len()` methods. The first is useful for
 verification of streamed data. The second is useful e.g. for replacing invalid byte sequences with a replacement character.
 
 It also fails early: errors are checked on the fly as the string is processed and once
 an invalid UTF-8 sequence is encountered, it returns without processing the rest of the data.
-This comes at a performance penalty compared to the `basic` API even if the input is valid UTF-8.
+This comes at a slight performance penalty compared to the `basic` API even if the input is valid UTF-8.
 
 ## Implementation selection
-The fastest implementation is selected at runtime using the `std::is_x86_feature_detected!` macro unless the CPU
+
+### X86
+The fastest implementation is selected at runtime using the `std::is_x86_feature_detected!` macro, unless the CPU
 targeted by the compiler supports the fastest available implementation.
 So if you compile with `RUSTFLAGS="-C target-cpu=native"` on a recent x86-64 machine, the AVX 2 implementation is selected at
 compile-time and runtime selection is disabled.
@@ -76,10 +84,18 @@ the targeted CPU. Use `RUSTFLAGS="-C target-feature=+avx2"` for the AVX 2 implem
 for the SSE 4.2 implementation.
 
 If you want to be able to call a SIMD implementation directly, use the `public_imp` feature flag. The validation
-implementations are then accessible via `simdutf8::(basic|compat)::imp::x86::(avx2|sse42)::validate_utf8()`.
+implementations are then accessible via `simdutf8::{basic, compat}::imp::x86::{avx2, sse42}::validate_utf8()`.
+
+### ARM64
+For ARM64 support Nightly Rust is needed and the crate feature `aarch64_neon` needs to be enabled. CAVE: If this features is
+not turned on the non-SIMD std library implementation is used.
+
+If you want to be able to call a SIMD implementation directly, use the `public_imp` feature flag. The validation implementations
+are then accessible via `simdutf8::{basic, compat}::imp::aarch64::neon::validate_utf8()`.
 
-## When not to use
-This library uses unsafe code which has not been battle-tested and should not (yet) be used in production.
+## Optimisation flags
+Do not use [`opt-level = "z"`](https://doc.rust-lang.org/cargo/reference/profiles.html), which prevents inlining and makes
+the code quite slow.
 
 ## Minimum Supported Rust Version (MSRV)
 This crate's minimum supported Rust version is 1.38.0.
@@ -90,50 +106,48 @@ are created with [critcmp](https://github.com/BurntSushi/critcmp). Source code a
 [bench directory](https://github.com/rusticstuff/simdutf8/tree/main/bench).
 
 The naming schema is id-charset/size. _0-empty_ is the empty byte slice, _x-error/66536_ is a 64KiB slice where the very
-first character is invalid UTF-8. All benchmarks were run on a laptop with an Intel Core i7-10750H CPU (Comet Lake) on
-Windows with Rust 1.51.0 if not otherwise stated. Library versions are simdutf8 v0.1.1 and simdjson v0.9.2. When comparing
+first character is invalid UTF-8. Library versions are simdutf8 v0.1.2 and simdjson v0.9.2. When comparing
 with simdjson simdutf8 is compiled with `#inline(never)`.
 
-### simdutf8 basic vs std library UTF-8 validation
-![critcmp stimdutf8 v0.1.1 basic vs std lib](https://user-images.githubusercontent.com/3736990/116121179-a8271f80-a6c0-11eb-9b2b-6233c3c824f2.png)
-simdutf8 performs better or as well as the std library.
+Configurations:
+* X86-64: PC with an AMD Ryzen 7 PRO 3700 CPU (Zen2) on Linux with Rust 1.52.0
+* Aarch64: Macbook Air with an Apple M1 CPU (Apple Silicon) on macOS with Rust rustc 1.54.0-nightly (881c1ac40 2021-05-08).
 
-### simdutf8 basic vs simdjson UTF-8 validation on Intel Comet Lake
-![critcmp stimdutf8 v0.1.1 basic vs simdjson WSL](https://user-images.githubusercontent.com/3736990/116121748-38656480-a6c1-11eb-8cb4-385c7516a46a.png)
-simdutf8 beats simdjson on almost all inputs on this CPU. This benchmark is run on 
-[WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10) 
-since I could not get simdjson to reach maximum performance on Windows with any C++ toolchain (see also simdjson issues 
-[847](https://github.com/simdjson/simdjson/issues/847) and [848](https://github.com/simdjson/simdjson/issues/848)).
+### simdutf8 basic vs std library on x86-64 (AMD Zen2)
+![image](https://user-images.githubusercontent.com/3736990/117568104-1c00f900-b0bf-11eb-938f-4c253d192480.png)
+Simdutf8 is up to 23 times faster than the std library on valid non-ASCII, up to four times on pure ASCII.
 
-### simdutf8 basic vs simdjson UTF-8 validation on AMD Zen 2
-![critcmp stimdutf8 v0.1.1 basic vs simdjson AMD Zen 2](https://user-images.githubusercontent.com/3736990/116122729-731bcc80-a6c2-11eb-82a5-6e297778a1c4.png)
+### simdutf8 basic vs std library on aarch64 (Apple Silicon)
+![image](https://user-images.githubusercontent.com/3736990/117568160-42bf2f80-b0bf-11eb-86a4-9aeee4cee87d.png)
+Simdutf8 is up to to eleven times faster than the std library on valid non-ASCII, up to four times faster on
+pure ASCII.
 
-On AMD Zen 2 aligning reads apparently does not matter at all. The extra step for aligning even hurts performance a bit around
-an input size of 4096.
+### simdutf8 basic vs simdjson on x86-64
+![image](https://user-images.githubusercontent.com/3736990/117568231-80bc5380-b0bf-11eb-8e90-1dcc6d966ebd.png)
+Simdutf8 is faster than simdjson on almost all inputs.
 
-### simdutf8 basic vs simdutf8 compat UTF-8 validation
-![image](https://user-images.githubusercontent.com/3736990/116122427-0dc7db80-a6c2-11eb-8434-f9879742d90d.png)
+### simdutf8 basic vs simdutf8 compat UTF-8 on x86-64
+![image](https://user-images.githubusercontent.com/3736990/117568270-af3a2e80-b0bf-11eb-8ec4-e5a0a4ad7210.png)
 There is a small performance penalty to continuously checking the error status while processing data, but detecting
 errors early provides a huge benefit for the _x-error/66536_ benchmark.
 
 ## Technical details
-On X86 for inputs shorter than 64 bytes validation is delegated to `core::str::from_utf8()`.
+For inputs shorter than 64 bytes validation is delegated to `core::str::from_utf8()` except for the direct-access
+functions in `simdutf8::{basic, compat}::imp`.
 
-The SIMD implementation is similar to the one in simdjson except that it aligns reads to the block size of the
-SIMD extension, which leads to better peak performance compared to the implementation in simdjson on some CPUs.
-This alignment means that an incomplete block needs to be processed before the aligned data is read, which
-leads to worse performance on byte sequences shorter than 2048 bytes. Thus, aligned reads are only used with
-2048 bytes of data or more. Incomplete reads for the first unaligned and the last incomplete block are done in
-two aligned 64-byte buffers.
+The SIMD implementation is mostly similar to the one in simdjson except that it is has additional optimizations
+for the pure ASCII case. Also it uses prefetch with AVX 2 on x86 which leads to slightly better performance with
+some Intel CPUs on synthetic benchmarks.
 
-For the compat API, we need to check the error buffer on each 64-byte block instead of just aggregating it. If an
+For the compat API, we need to check the error status vector on each 64-byte block instead of just aggregating it. If an
 error is found, the last bytes of the previous block are checked for a cross-block continuation and then
 `std::str::from_utf8()` is run to find the exact location of the error.
 
 Care is taken that all functions are properly inlined up to the public interface.
 
 ## Thanks
-* to the authors of simdjson for coming up with the high-performance SIMD implementation.
+* to the authors of simdjson for coming up with the high-performance SIMD implementation and in particular to Daniel Lemire
+  for his feedback. It was very helpful.
 * to the authors of the simdjson Rust port who did most of the heavy lifting of porting the C++ code to Rust.
 
 

TODO.md

@@ -1,27 +1,19 @@
 # TODO
 
 # LATER
-* test coverage
-* more fuzz testing
 * armv7 support (with neon runtime selection?)
-* fuzzers: extract common code into crate/module and add honggfuzz
 * streaming API + experimental simdjson support
 * faster/smarter error position detection
 * try out [multiversion](https://docs.rs/multiversion/0.6.1/multiversion/)
-
-# NEXT
+* test all available stable implementations by default as if public_imp were specified
+* try proptests again
 * clean up algorithm src.
   * document prev()
   * newtype -> use (mostly)
   * use imports instead of fully qualified at places
   * trait for SimdU8Value impl.
   * bikeshed: SimdU8Value -> SimdU8Vector | SimdU8xNative | ...
 
-* test all available stable implementations by default as if public_imp were specified
-* document aarch64; docs-rs arch building
-* discourage -Oz
-* std handling: no-std + extern crate std if std
-* Doc: remove for Rust from README header but not from description
-* proptests?
+# NEXT
 
 # OTHER