Skip to content

Commit fc5d2b7

Browse files
authored
Merge pull request #379 from gyscos/fix/pr-378-rust-allocator
Add Rust allocator feature with safety fixes and isolated tests
2 parents be539f1 + 18028cd commit fc5d2b7

18 files changed

Lines changed: 1033 additions & 56 deletions

‎.github/workflows/lint.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,10 @@ jobs:
3030
run: cargo clippy --all-targets -- -D warnings
3131
- name: Clippy with features
3232
run: cargo clippy --all-targets --features experimental,zstdmt -- -D warnings
33+
- name: Clippy with Rust allocator
34+
run: |
35+
cargo clippy --all-targets --features with-rust-allocator,zstdmt -- -D warnings
36+
cargo clippy --manifest-path zstd-safe/Cargo.toml --all-targets --features std,with-rust-allocator -- -D warnings
3337
- name: Clippy zstd-safe
3438
run: |
3539
cargo clippy --manifest-path zstd-safe/Cargo.toml --all-targets \

‎.github/workflows/linux.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,15 @@ jobs:
2828
- name: Run tests
2929
run: cargo test --verbose --features thin
3030

31+
- name: Build with feature with-rust-allocator
32+
run: cargo build --verbose --features with-rust-allocator
33+
- name: Run tests with feature with-rust-allocator
34+
run: cargo test --verbose --features with-rust-allocator
35+
- name: Run zstd-safe tests with Rust allocator
36+
run: cargo test --manifest-path zstd-safe/Cargo.toml --verbose --features std,with-rust-allocator
37+
- name: Check zstd-safe Rust allocator without std
38+
run: cargo check --manifest-path zstd-safe/Cargo.toml --no-default-features --features with-rust-allocator
39+
3140
- name: Build zstd-safe with feature seekable
3241
run: cargo build --manifest-path zstd-safe/Cargo.toml --verbose --features seekable
3342
- name: Run zstd-safe tests with feature seekable

‎.github/workflows/windows.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,3 +56,7 @@ jobs:
5656
run: cargo build --verbose --verbose
5757
- name: Run tests
5858
run: cargo test --verbose
59+
- name: Run tests with Rust allocator
60+
run: |
61+
cargo test --verbose --features with-rust-allocator
62+
cargo test --manifest-path zstd-safe/Cargo.toml --verbose --features std,with-rust-allocator

‎Cargo.toml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,9 @@ cmake = ["zstd-safe/cmake"]
4242
no_asm = ["zstd-safe/no_asm"]
4343
doc-cfg = []
4444
zdict_builder = ["zstd-safe/zdict_builder"]
45+
# Route every allocation zstd makes for contexts and dictionaries through
46+
# Rust's global allocator instead of the C runtime's malloc/free.
47+
with-rust-allocator = ["zstd-safe/with-rust-allocator"]
4548

4649
# These two are for cross-language LTO.
4750
# Will only work if `clang` is used to build the C library.

‎Readme.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -166,6 +166,37 @@ git submodule update --init
166166
Then, running `cargo build` should take care
167167
of building the C library and linking to it.
168168

169+
# Using Rust's global allocator
170+
171+
By default, zstd allocates its internal state (compression windows, match
172+
finder tables, stream buffers, dictionaries) with the C runtime's
173+
`malloc`/`free`, invisible to a custom `#[global_allocator]`.
174+
175+
The `with-rust-allocator` feature makes every context and dictionary this
176+
crate creates (`Encoder`, `Decoder`, `bulk::Compressor`, dictionaries, ...)
177+
allocate through Rust's global allocator instead. It is crate-wide: enabling
178+
it in your own `Cargo.toml` also covers `zstd` usage inside your
179+
dependencies, since Cargo unifies features.
180+
181+
```toml
182+
zstd = { version = "0.14", features = ["with-rust-allocator"] }
183+
```
184+
185+
The feature implies `experimental` on `zstd-safe` because it relies on zstd's
186+
`ZSTD_create*_advanced()` constructors, which require static linking. It
187+
applies to contexts and prepared dictionaries created by the Rust wrappers,
188+
including clones. Direct calls to `zstd_sys`, dictionary training, legacy
189+
frame decoding, objects from the `seekable` format, and explicit zstd thread
190+
pools can still allocate through C.
191+
192+
Prepared compression dictionaries use fixed parameters derived from their
193+
compression level and dictionary size. Unlike the default C constructor,
194+
the custom-allocator constructor does not store the level for later parameter
195+
adjustments based on the input size. Compressed output remains interoperable,
196+
but enabling this feature can change compression ratio, speed, and memory
197+
usage for prepared dictionaries, especially with large inputs and small
198+
dictionaries.
199+
169200
# Build-time bindgen
170201

171202
This library includes a pre-generated `bindings.rs` file.

‎tests/support/rust_allocator.rs‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
// Shared by separate test binaries to isolate process-wide counters.
2+
use std::alloc::{GlobalAlloc, Layout, System};
3+
use std::sync::atomic::{AtomicUsize, Ordering::Relaxed};
4+
5+
/// Bytes currently held through the global allocator.
6+
pub static LIVE_BYTES: AtomicUsize = AtomicUsize::new(0);
7+
/// Bytes ever requested from the global allocator (monotonic).
8+
pub static TOTAL_BYTES: AtomicUsize = AtomicUsize::new(0);
9+
10+
struct CountingAllocator;
11+
12+
unsafe impl GlobalAlloc for CountingAllocator {
13+
unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
14+
let ptr = System.alloc(layout);
15+
if !ptr.is_null() {
16+
LIVE_BYTES.fetch_add(layout.size(), Relaxed);
17+
TOTAL_BYTES.fetch_add(layout.size(), Relaxed);
18+
}
19+
ptr
20+
}
21+
22+
unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
23+
LIVE_BYTES.fetch_sub(layout.size(), Relaxed);
24+
System.dealloc(ptr, layout)
25+
}
26+
}
27+
28+
#[global_allocator]
29+
static GLOBAL: CountingAllocator = CountingAllocator;

‎tests/with_rust_allocator.rs‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
#![cfg(feature = "with-rust-allocator")]
2+
3+
mod support {
4+
pub mod rust_allocator;
5+
}
6+
7+
use std::sync::atomic::Ordering::Relaxed;
8+
use support::rust_allocator::LIVE_BYTES;
9+
10+
fn input() -> Vec<u8> {
11+
b"the quick brown fox jumps over the lazy dog; ".repeat(10_000)
12+
}
13+
14+
const WORKSPACE_FLOOR: usize = 512 * 1024;
15+
16+
#[test]
17+
fn bulk_api_uses_global_allocator() {
18+
let input = input();
19+
let mut compressed = Vec::with_capacity(input.len());
20+
let mut decompressed = vec![0u8; input.len()];
21+
22+
let before = LIVE_BYTES.load(Relaxed);
23+
{
24+
let mut compressor =
25+
zstd::bulk::Compressor::new(3).expect("compressor");
26+
compressor
27+
.compress_to_buffer(&input, &mut compressed)
28+
.expect("compression failed");
29+
assert!(
30+
LIVE_BYTES.load(Relaxed) - before > WORKSPACE_FLOOR,
31+
"bulk::Compressor workspace is not visible to the global allocator"
32+
);
33+
}
34+
assert_eq!(LIVE_BYTES.load(Relaxed), before, "bulk::Compressor leaked");
35+
36+
let before = LIVE_BYTES.load(Relaxed);
37+
{
38+
let mut decompressor =
39+
zstd::bulk::Decompressor::new().expect("decompressor");
40+
let n = decompressor
41+
.decompress_to_buffer(&compressed, &mut decompressed[..])
42+
.expect("decompression failed");
43+
assert_eq!(n, input.len());
44+
assert!(
45+
LIVE_BYTES.load(Relaxed) > before,
46+
"bulk::Decompressor is not visible to the global allocator"
47+
);
48+
}
49+
assert_eq!(
50+
LIVE_BYTES.load(Relaxed),
51+
before,
52+
"bulk::Decompressor leaked"
53+
);
54+
assert_eq!(input, decompressed);
55+
}
Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
#![cfg(feature = "with-rust-allocator")]
2+
3+
mod support {
4+
pub mod rust_allocator;
5+
}
6+
7+
use std::io::{Read, Write};
8+
use std::sync::atomic::Ordering::Relaxed;
9+
use support::rust_allocator::{LIVE_BYTES, TOTAL_BYTES};
10+
11+
fn input() -> Vec<u8> {
12+
b"the quick brown fox jumps over the lazy dog; ".repeat(10_000)
13+
}
14+
15+
const WORKSPACE_FLOOR: usize = 512 * 1024;
16+
17+
#[test]
18+
fn dictionaries_use_global_allocator() {
19+
let input = input();
20+
let dict: Vec<u8> = (0..=255u8).cycle().take(4096).collect();
21+
22+
let before = LIVE_BYTES.load(Relaxed);
23+
let compressed = {
24+
let mut encoder = zstd::Encoder::with_dictionary(Vec::new(), 3, &dict)
25+
.expect("encoder");
26+
encoder.write_all(&input).expect("compression failed");
27+
assert!(
28+
LIVE_BYTES.load(Relaxed) - before > WORKSPACE_FLOOR,
29+
"Encoder::with_dictionary workspace is not visible to the \
30+
global allocator"
31+
);
32+
encoder.finish().expect("failed to finish frame")
33+
};
34+
assert_eq!(
35+
LIVE_BYTES.load(Relaxed) - before,
36+
compressed.capacity(),
37+
"Encoder::with_dictionary leaked"
38+
);
39+
40+
let before = LIVE_BYTES.load(Relaxed);
41+
{
42+
let prepared = zstd::dict::EncoderDictionary::copy(&dict, 3);
43+
assert!(
44+
LIVE_BYTES.load(Relaxed) - before >= prepared.as_cdict().sizeof(),
45+
"EncoderDictionary::copy is not visible to the global allocator"
46+
);
47+
let prepared = zstd::dict::DecoderDictionary::copy(&dict);
48+
assert!(
49+
LIVE_BYTES.load(Relaxed) - before >= prepared.as_ddict().sizeof(),
50+
"DecoderDictionary::copy is not visible to the global allocator"
51+
);
52+
}
53+
assert_eq!(
54+
LIVE_BYTES.load(Relaxed),
55+
before,
56+
"prepared dictionaries leaked"
57+
);
58+
59+
let before = LIVE_BYTES.load(Relaxed);
60+
let mut roundtrip = Vec::with_capacity(input.len());
61+
{
62+
let prepared = zstd::dict::DecoderDictionary::copy(&dict);
63+
let mut decoder = zstd::Decoder::with_prepared_dictionary(
64+
compressed.as_slice(),
65+
&prepared,
66+
)
67+
.expect("decoder");
68+
decoder
69+
.read_to_end(&mut roundtrip)
70+
.expect("decompression failed");
71+
}
72+
assert_eq!(
73+
LIVE_BYTES.load(Relaxed) - before,
74+
roundtrip.capacity(),
75+
"Decoder::with_prepared_dictionary leaked"
76+
);
77+
assert_eq!(input, roundtrip);
78+
79+
// One-shot helpers.
80+
let total = TOTAL_BYTES.load(Relaxed);
81+
let live = LIVE_BYTES.load(Relaxed);
82+
let compressed =
83+
zstd::encode_all(input.as_slice(), 3).expect("encode_all");
84+
let decoded = zstd::decode_all(compressed.as_slice()).expect("decode_all");
85+
assert!(TOTAL_BYTES.load(Relaxed) - total > WORKSPACE_FLOOR);
86+
drop((compressed, decoded));
87+
assert_eq!(
88+
LIVE_BYTES.load(Relaxed),
89+
live,
90+
"encode_all/decode_all leaked"
91+
);
92+
}
Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
#![cfg(feature = "with-rust-allocator")]
2+
3+
mod support {
4+
pub mod rust_allocator;
5+
}
6+
7+
use std::io::{Read, Write};
8+
use std::sync::atomic::Ordering::Relaxed;
9+
use support::rust_allocator::LIVE_BYTES;
10+
11+
fn input() -> Vec<u8> {
12+
b"the quick brown fox jumps over the lazy dog; ".repeat(10_000)
13+
}
14+
15+
const WORKSPACE_FLOOR: usize = 512 * 1024;
16+
17+
#[test]
18+
fn stream_api_uses_global_allocator() {
19+
let input = input();
20+
21+
let before = LIVE_BYTES.load(Relaxed);
22+
let compressed = {
23+
let mut encoder = zstd::Encoder::new(Vec::new(), 3).expect("encoder");
24+
encoder.write_all(&input).expect("compression failed");
25+
assert!(
26+
LIVE_BYTES.load(Relaxed) - before > WORKSPACE_FLOOR,
27+
"stream Encoder workspace is not visible to the global allocator"
28+
);
29+
encoder.finish().expect("failed to finish frame")
30+
};
31+
// Only the output Vec should still be alive.
32+
assert_eq!(
33+
LIVE_BYTES.load(Relaxed) - before,
34+
compressed.capacity(),
35+
"stream Encoder leaked"
36+
);
37+
38+
let before = LIVE_BYTES.load(Relaxed);
39+
let mut roundtrip = Vec::with_capacity(input.len());
40+
{
41+
let mut decoder =
42+
zstd::Decoder::new(compressed.as_slice()).expect("decoder");
43+
decoder
44+
.read_to_end(&mut roundtrip)
45+
.expect("decompression failed");
46+
assert!(
47+
LIVE_BYTES.load(Relaxed) - before > roundtrip.capacity(),
48+
"stream Decoder is not visible to the global allocator"
49+
);
50+
}
51+
assert_eq!(
52+
LIVE_BYTES.load(Relaxed) - before,
53+
roundtrip.capacity(),
54+
"stream Decoder leaked"
55+
);
56+
assert_eq!(input, roundtrip);
57+
}

‎zstd-safe/Cargo.toml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,10 @@ no_asm = ["zstd-sys/no_asm"]
3737
doc-cfg = []
3838
zdict_builder = ["zstd-sys/zdict_builder"]
3939
seekable = ["zstd-sys/seekable"]
40+
# Route every allocation zstd makes for contexts and dictionaries through
41+
# Rust's global allocator instead of the C runtime's malloc/free.
42+
# Needs the `_advanced` constructors, hence `experimental`.
43+
with-rust-allocator = ["experimental"]
4044

4145
# These two are for cross-language LTO.
4246
# Will only work if `clang` is used to build the C library.

0 commit comments

Comments
 (0)