mirror of
https://github.com/rust-lang/rust.git
synced 2026-04-28 03:07:24 +03:00
Jonathan Brouwer
cf951bae87
feat(rustdoc-json): Add optional support for rkyv (de)serialization ## Motivation The JSON documents produced by `rustdoc-json` are _big_. More often than not, tools need to access a small fraction of that output—e.g. a couple of types from a transitive dependency, or a subset of the fields on a given `rustdoc-json-types` type. Using a binary (de)serialization format and a cache helps to drive down the performance cost of deserialization: you invoke `rustdoc-json` to get the JSON output you need, re-serialize it using a more perfomant format as target (e.g. `bincode` or `postcard`) and thus amortize the cost of future queries that hit the persistent cache rather than `rustdoc-json`. This is _better_, but still not great: the deserialization cost for crates like `std` still shows up prominently in flamegraphs. ## An Alternative Approach: rkyv `rkyv` provides a different opportunity: you avoid paying the deserialization cost _upfront_ thanks to [zero-copy deserialization](https://rkyv.org/zero-copy-deserialization.html). You're often able to determine if you need a certain entry from the JSON document using the archived version of that type, thus incurring the full deserialization cost only for the subset of items you actually need ([example](https://github.com/LukeMathWalker/pavex/pull/574/changes/d067e7e0cfa38da5b0a3c8713b1c53beb0b29a5d)). ## The Change This PR adds support for `rkyv` behind a feature flag (`rkyv_0_8`). For most types, it's a straight-forward `derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)` annotation. For co-recursive types, we need to adjust the generated bounds, using the techniques from [`rkyv`'s JSON example](https://github.com/rkyv/rkyv/blob/985b0230a0b9cb9fce4a4ee9facb6af148e27c8e/rkyv/examples/json_like_schema.rs). I have added new round-trip tests to ensure `rkyv` works as expected. r? @aDotInTheVoid
Rustdoc JSON Types
This crate exposes the Rustdoc JSON API as a set of types with serde implementations. These types are part of the public interface of the rustdoc JSON output, and making them their own crate allows them to be versioned and distributed without having to depend on any rustc/rustdoc internals. This way, consumers can rely on this crate for both documentation of the output, and as a way to read the output easily, and its versioning is intended to follow semver guarantees about the version of the format. JSON format X will always be compatible with rustdoc-json-types version N.
Currently, this crate is only used by rustdoc itself. Upon the stabilization of rustdoc-json, it may be distributed separately for consumers of the API.