docs(rust): refresh migration boundary
Update the Rust rewrite documentation to match the current implementation boundary. The legacy decoder set is complete, and Rust now owns several CLI file-I/O policy and resource leaves while C retains format dispatch, metadata, and remaining orchestration. Keep the stated boundary explicit so passing hybrid tests do not imply that the full rewrite is finished. Test Plan: - git diff --cached --check
This commit is contained in:
+20
-19
@@ -66,8 +66,9 @@ zstd ABI:
|
|||||||
- `zstd_ddict` owns, loads, copies, and references decode dictionaries.
|
- `zstd_ddict` owns, loads, copies, and references decode dictionaries.
|
||||||
- Legacy decoding
|
- Legacy decoding
|
||||||
- `legacy` hosts one frozen module per historical format; `legacy::zstd_v01`
|
- `legacy` hosts one frozen module per historical format; `legacy::zstd_v01`
|
||||||
ports the self-contained v0.1 decoder. Versions v0.2 through v0.7 are
|
through `legacy::zstd_v07` port the seven self-contained historical
|
||||||
still C.
|
decoders. Their original C translation units remain declaration-only
|
||||||
|
shims for the native build.
|
||||||
- Block decompression
|
- Block decompression
|
||||||
- `zstd_decompress_block` decodes literal and sequence sections, maintains
|
- `zstd_decompress_block` decodes literal and sequence sections, maintains
|
||||||
FSE/Huffman repeat state, and executes compressed-block sequences.
|
FSE/Huffman repeat state, and executes compressed-block sequences.
|
||||||
@@ -78,8 +79,10 @@ zstd ABI:
|
|||||||
- `zstd_cli` owns the Rust parser, safety policy, and dispatch. It is built
|
- `zstd_cli` owns the Rust parser, safety policy, and dispatch. It is built
|
||||||
by the separate `cli/` static-library package only for program archives,
|
by the separate `cli/` static-library package only for program archives,
|
||||||
so library builds do not acquire program-only dependencies. The C
|
so library builds do not acquire program-only dependencies. The C
|
||||||
`fileio` backend still owns file opening, safe replacement, sparse writes,
|
`fileio` layer still owns format-specific dispatch, metadata, and the
|
||||||
metadata, and streaming I/O.
|
remaining C streaming/orchestration paths. Rust already owns the file
|
||||||
|
preference policy, filename decisions, source/destination opening,
|
||||||
|
dictionary buffers, asynchronous I/O pools, and pass-through copy leaf.
|
||||||
- `timefn` provides the monotonic nanosecond clock behind `UTIL_time_t`,
|
- `timefn` provides the monotonic nanosecond clock behind `UTIL_time_t`,
|
||||||
and `benchfn` owns the benchmark run/timing loop (`BMK_benchFunction`,
|
and `benchfn` owns the benchmark run/timing loop (`BMK_benchFunction`,
|
||||||
`BMK_benchTimedFn`) used by the CLI benchmark mode and by C test tools.
|
`BMK_benchTimedFn`) used by the CLI benchmark mode and by C test tools.
|
||||||
@@ -90,12 +93,12 @@ zstd ABI:
|
|||||||
orchestration and reporting (`benchzstd.c`) remain C, reached from the
|
orchestration and reporting (`benchzstd.c`) remain C, reached from the
|
||||||
Rust parser through the `ZSTD_NOBENCH`-gated bridge in `zstdcli.c`.
|
Rust parser through the `ZSTD_NOBENCH`-gated bridge in `zstdcli.c`.
|
||||||
|
|
||||||
The optimal block matcher, high-level frame compression, dictionary-building
|
The optimal block matcher, most high-level frame-compression orchestration,
|
||||||
except suffix-array construction, the legacy v0.2-v0.7 decoders, benchmark
|
dictionary-building except suffix-array construction, benchmark orchestration
|
||||||
orchestration (`benchzstd`), and the CLI file-I/O backend are still C. They
|
and reporting (`benchzstd`), and several format-specific CLI I/O paths are
|
||||||
must move before the rewrite is complete. Keeping that boundary explicit
|
still C. They must move before the rewrite is complete. Keeping that boundary
|
||||||
prevents a passing hybrid build from being mistaken for the final all-Rust
|
explicit prevents a passing hybrid build from being mistaken for the final
|
||||||
result.
|
all-Rust result.
|
||||||
|
|
||||||
## Legacy decoding
|
## Legacy decoding
|
||||||
|
|
||||||
@@ -108,8 +111,8 @@ byte-identical to the original C files. Their only shared dependency is the
|
|||||||
`errors` module, matching the C files' `error_private.h` include.
|
`errors` module, matching the C files' `error_private.h` include.
|
||||||
|
|
||||||
Cargo features `legacy-v01` .. `legacy-v07` gate the per-version modules and
|
Cargo features `legacy-v01` .. `legacy-v07` gate the per-version modules and
|
||||||
are never default features. The build systems derive the feature list from
|
are never default features. All seven modules are now available; the build
|
||||||
the C configuration:
|
systems derive the enabled feature list from the C configuration:
|
||||||
|
|
||||||
- `lib/Makefile` and `programs/Makefile` map `ZSTD_LEGACY_SUPPORT=N` to the
|
- `lib/Makefile` and `programs/Makefile` map `ZSTD_LEGACY_SUPPORT=N` to the
|
||||||
features for versions >= N (0 disables legacy), matching the
|
features for versions >= N (0 disables legacy), matching the
|
||||||
@@ -125,13 +128,11 @@ directory name (for example `c1-d1-default-legacy5`), for the same reason the
|
|||||||
HUF mode is encoded there: a cached archive built for one configuration must
|
HUF mode is encoded there: a cached archive built for one configuration must
|
||||||
never be linked into a build that expects another.
|
never be linked into a build that expects another.
|
||||||
|
|
||||||
A feature whose version has not been ported yet gates nothing; the original
|
Each port adds `src/legacy/zstd_v0N.rs`, registers it in `src/legacy/mod.rs`
|
||||||
C file still provides that decoder, so mixed C/Rust legacy levels link
|
behind its feature, and reduces `lib/legacy/zstd_v0N.c` to a
|
||||||
cleanly. Porting a version means adding `src/legacy/zstd_v0N.rs`, registering
|
declaration-only shim. For v0.1 the streaming `ZSTDv01_Dctx` state lives
|
||||||
it in `src/legacy/mod.rs` behind its feature, and reducing
|
entirely in Rust: C code only ever holds an opaque pointer, so the C-side
|
||||||
`lib/legacy/zstd_v0N.c` to a declaration-only shim. For v0.1 the streaming
|
struct definition is gone.
|
||||||
`ZSTDv01_Dctx` state lives entirely in Rust: C code only ever holds an opaque
|
|
||||||
pointer, so the C-side struct definition is gone.
|
|
||||||
|
|
||||||
## Compatibility boundary
|
## Compatibility boundary
|
||||||
|
|
||||||
|
|||||||
@@ -4,11 +4,13 @@
|
|||||||
|
|
||||||
//! Rust command-line frontend for zstd.
|
//! Rust command-line frontend for zstd.
|
||||||
//!
|
//!
|
||||||
//! This is intentionally a parser and dispatch layer, not a second file I/O
|
//! This is the Rust parser and dispatch layer plus selected file-I/O leaves,
|
||||||
//! implementation. It reuses the mature C `fileio` layer through its narrow
|
//! not yet a fully independent file-I/O implementation. It shares the
|
||||||
//! public-in-the-programs-tree ABI: file opening, safe replacement, sparse
|
//! mature C `fileio` layer through a narrow public-in-the-programs-tree ABI:
|
||||||
//! writes, dictionary loading, streaming, and metadata preservation remain in
|
//! Rust owns preference policy, filename decisions, file opening, dictionary
|
||||||
//! `programs/fileio.c` for this first migration step.
|
//! loading, asynchronous pools, and pass-through copying, while C still owns
|
||||||
|
//! format-specific dispatch, metadata preservation, and remaining streaming
|
||||||
|
//! orchestration.
|
||||||
//!
|
//!
|
||||||
//! Benchmark mode (`-b`) parses and dispatches through the Rust CLI archive.
|
//! Benchmark mode (`-b`) parses and dispatches through the Rust CLI archive.
|
||||||
//! The bridge preserves the C CLI's argument normalization and uses the
|
//! The bridge preserves the C CLI's argument normalization and uses the
|
||||||
|
|||||||
Reference in New Issue
Block a user