From 3514a643c3c361713fe8f695cf1c1fe05509d096 Mon Sep 17 00:00:00 2001 From: Folkert de Vries Date: Mon, 16 Dec 2024 12:09:19 +0100 Subject: [PATCH 1/2] add info about flags to readme --- README.md | 41 +++++++++++++++++++++++++++++++----- libz-rs-sys-cdylib/README.md | 31 +++++++++++++++++++++++++++ 2 files changed, 67 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index fb5fb2d6..d4e00a2e 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ # zlib-rs: a safer zlib -This repository contains a Rust implementation of the zlib file format that is compatible with the zlib API. +This repository contains a Rust implementation of the zlib file format that is compatible with the zlib API. This repository contains two public crates: @@ -23,14 +23,43 @@ zlib-rs can be used in both Rust and C projects. By far the easiest way to use zlib-rs is through the [flate2](https://crates.io/crates/flate2) crate, by simply enabling the `zlib-rs` feature gate. This will enable the `zlib-rs` backend. -## C projects +### C projects zlib-rs can be built as a shared object file for usage by C programs that dynamically link to zlib. Please see the example in [libz-rs-sys-cdylib](https://github.com/trifectatechfoundation/zlib-rs/tree/main/libz-rs-sys-cdylib). -## Acknowledgment +## Performance -This project is heavily based on the [zlib](https://github.com/madler/zlib) and -[zlib-ng](https://github.com/zlib-ng/zlib-ng) projects. +Performance is generally on-par with [zlib-ng]. + +### Compiler Flags + +Compiler flags that can be used to improve performance. + +#### `-Ctarget-cpu=...` + +Providing more information about the SIMD capabilities of the target machine can improve performance. E.g. + +``` +RUSTFLAGS="-Ctarget-cpu=native" cargo build --release ... +``` + +The resulting binary statically assumes the SIMD capabilities of the current machine. + +Note: binaries built with `-Ctarget-cpu` almost certainly crash on systems that don't have the specified CPU! Only use this flag if you control how the binary is deployed, and can guarantee that the CPU assumptions are never violated. + +#### `-Cllvm-args=-enable-dfa-jump-thread` + +For best performance with very small input sizes, compile with: + +``` +RUSTFLAGS="-Cllvm-args=-enable-dfa-jump-thread" cargo build --release ... +``` + +This flag gives around a 10% boost when the input arrives in chunks of 16 bytes, and a couple percent when input arrives in chunks of under 1024 bytes. Beyond that, the effect is not significant. Using this flag can lead to longer compile times, but otherwise has no adverse effects. + +## Acknowledgments + +This project is heavily based on the [zlib](https://github.com/madler/zlib) and [zlib-ng] projects. ## About @@ -39,3 +68,5 @@ zlib-rs is part of Trifecta Tech Foundation's [Data compression initiative](http ## History The initial development of zlib-rs was started and funded by the [Internet Security Research Group](https://www.abetterinternet.org/) as part of the [Prossimo project](https://www.memorysafety.org/). + +[zlib-ng]: https://github.com/zlib-ng/zlib-ng diff --git a/libz-rs-sys-cdylib/README.md b/libz-rs-sys-cdylib/README.md index 5db9c9cf..bc2054d5 100644 --- a/libz-rs-sys-cdylib/README.md +++ b/libz-rs-sys-cdylib/README.md @@ -112,3 +112,34 @@ target ├── libz_rs.so └── libz_rs-uninstalled.pc ``` + +## Performance + +Performance is generally on-par with [zlib-ng]. + +### Compiler Flags + +Compiler flags that can be used to improve performance. + +#### `-Ctarget-cpu=...` + +Providing more information about the SIMD capabilities of the target machine can improve performance. E.g. + +``` +RUSTFLAGS="-Ctarget-cpu=native" cargo build --release ... +``` + +The resulting binary statically assumes the SIMD capabilities of the current machine. + +Note: binaries built with `-Ctarget-cpu` almost certainly crash on systems that don't have the specified CPU! Only use this flag if you control how the binary is deployed, and can guarantee that the CPU assumptions are never violated. + +#### `-Cllvm-args=-enable-dfa-jump-thread` + +For best performance with very small input sizes, compile with: + +``` +RUSTFLAGS="-Cllvm-args=-enable-dfa-jump-thread" cargo build --release ... +``` + +This flag gives around a 10% boost when the input arrives in chunks of 16 bytes, and a couple percent when input arrives in chunks of under 1024 bytes. Beyond that, the effect is not significant. Using this flag can lead to longer compile times, but otherwise has no adverse effects. + From 82862aeb8dcfb4137d44a59a9175a177d0cb9721 Mon Sep 17 00:00:00 2001 From: Folkert de Vries Date: Mon, 16 Dec 2024 09:50:51 +0100 Subject: [PATCH 2/2] release version 0.4.1 --- Cargo.toml | 6 +++--- docs/release.md | 1 + libz-rs-sys-cdylib/Cargo.toml | 4 ++-- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 842438c0..dee034bf 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -15,7 +15,7 @@ resolver = "2" # Global settings for our crates [workspace.package] -version = "0.4.0" +version = "0.4.1" edition = "2021" license = "Zlib" repository = "https://github.com/trifectatechfoundation/zlib-rs" @@ -37,7 +37,7 @@ libz-sys = { version = "1.1.19", default-features = false, features = ["zlib-ng" arbitrary = { version = "1.0" } quickcheck = { version = "1.0.3", default-features = false, features = [] } -libz-rs-sys = { version = "0.4.0", path = "./libz-rs-sys", default-features = false } -zlib-rs = { version = "0.4.0", path = "./zlib-rs", default-features = false } +libz-rs-sys = { version = "0.4.1", path = "./libz-rs-sys", default-features = false } +zlib-rs = { version = "0.4.1", path = "./zlib-rs", default-features = false } dynamic-libz-sys = { path = "./dynamic-libz-sys" } diff --git a/docs/release.md b/docs/release.md index ffb1c728..7f253b1a 100644 --- a/docs/release.md +++ b/docs/release.md @@ -15,6 +15,7 @@ - [ ] Run `cargo clean` - [ ] Run `cargo build --release` - [ ] Run `cargo test --release` +- [ ] Run `(cd libz-rs-sys-cdylib && cargo check)` - [ ] `git commit -a -S -m "Release $VERSION"` (where `$VERSION` is the actual version to be released, making sure the commit is signed) - [ ] Run `cargo publish --dry-run -p zlib-rs` diff --git a/libz-rs-sys-cdylib/Cargo.toml b/libz-rs-sys-cdylib/Cargo.toml index 974ed6b2..660a6af5 100644 --- a/libz-rs-sys-cdylib/Cargo.toml +++ b/libz-rs-sys-cdylib/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "libz-rs-sys-cdylib" -version = "0.4.0" +version = "0.4.1" edition = "2021" readme = "README.md" license = "Zlib" @@ -22,7 +22,7 @@ custom-prefix = ["libz-rs-sys/custom-prefix"] # use the LIBZ_RS_SYS_PREFIX to pr capi = [] [dependencies] -libz-rs-sys = { version = "0.4.0", path = "../libz-rs-sys", default-features = false } +libz-rs-sys = { version = "0.4.1", path = "../libz-rs-sys", default-features = false } [package.metadata.capi.library] version = "1.3.0" # the zlib api version we match