mirror
/
rustc-dev-guide
mirror of https://github.com/rust-lang/rustc-dev-guide.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

updates documentation

This commit is contained in:
Tbkhi 2024-03-05 10:34:12 -04:00 committed by nora
parent fb88f31f79
commit 6803fdb36b
1 changed files with 57 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

94
src/serialization.md
View File

@ -12,6 +12,10 @@ compilation. Specifically:
- [`CrateInfo`] is serialized to `JSON` when the `-Z no-link` flag is used, and - [`CrateInfo`] is serialized to `JSON` when the `-Z no-link` flag is used, and
deserialized from `JSON` when the `-Z link-only` flag is used. deserialized from `JSON` when the `-Z link-only` flag is used.
[`CrateInfo`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/struct.CrateInfo.html
[persist incremental compilation results]: queries/incremental-compilation-in-detail.md#the-real-world-how-persistence-makes-everything-complicated
[serialize]: https://en.wikipedia.org/wiki/Serialization
## The `Encodable` and `Decodable` traits ## The `Encodable` and `Decodable` traits
The [`rustc_serialize`] crate defines two traits for types which can be serialized: The [`rustc_serialize`] crate defines two traits for types which can be serialized:
@ -26,13 +30,14 @@ pub trait Decodable<D: Decoder>: Sized {
} }
``` ```
It also defines implementations of these for integer types, floating point It also defines implementations of these for various common standard library
types, `bool`, `char`, `str` and various common standard library types. [primitive types](https://doc.rust-lang.org/std/#primitives) such as integer
types, floating point types, `bool`, `char`, `str`, etc.
For types that are constructed from those types, `Encodable` and `Decodable` are For types that are constructed from those types, `Encodable` and `Decodable`
usually implemented by [derives]. These generate implementations that forward are usually implemented by [derives]. These generate implementations that
deserialization to the fields of the `struct` or `enum`. For a `struct` those `impl`s forward deserialization to the `field`s of the `struct` or `enum`. For a
look something like this: `struct` those `impl`s look something like this:
```rust,ignore ```rust,ignore
#![feature(rustc_private)] #![feature(rustc_private)]
@ -64,16 +69,17 @@ impl<D: Decoder> Decodable<D> for MyStruct {
} }
} }
``` ```
[`rustc_serialize`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_serialize/index.html
## Encoding and Decoding arena allocated types ## Encoding and Decoding arena allocated types
Rust's compiler has a lot of [arena allocated types]. Deserializing these types Rust's compiler has a lot of [arena allocated types]. Deserializing these types
isn't possible without access to the `arena` that they need to be allocated on. isn't possible without access to the `arena` that they need to be allocated on.
The [`TyDecoder`] and [`TyEncoder`] `trait`s are supertraits of `Decoder` and The [`TyDecoder`] and [`TyEncoder`] `trait`s are supertraits of [`Decoder`] and
`Encoder` that allow access to a `TyCtxt`. [`Encoder`] that allow access to a [`TyCtxt`].
Types which contain `arena` allocated types can then bound the type parameter Types which contain `arena` allocated types can then bound the type parameter
of their `Encodable` and `Decodable` implementations with these `trait`s. For of their [`Encodable`] and [`Decodable`] implementations with these `trait`s. For
example example
```rust,ignore ```rust,ignore
@ -82,38 +88,62 @@ impl<'tcx, D: TyDecoder<'tcx>> Decodable<D> for MyStruct<'tcx> {
} }
``` ```
The `TyEncodable` and `TyDecodable` [derive macros][derives] will expand to such The [`TyEncodable`] and [`TyDecodable`] [derive macros][derives] will expand to such
an implementation. an implementation.
Decoding the actual `arena` allocated type is harder, because some of the Decoding the actual `arena` allocated type is harder, because some of the
implementations can't be written due to the orphan rules. To work around this, implementations can't be written due to the [orphan rules]. To work around this,
the [`RefDecodable`] trait is defined in `rustc_middle`. This can then be the [`RefDecodable`] trait is defined in [`rustc_middle`]. This can then be
implemented for any type. The `TyDecodable` macro will call `RefDecodable` to implemented for any type. The `TyDecodable` macro will call `RefDecodable` to
decode references, but various generic code needs types to actually be decode references, but various generic code needs types to actually be
`Decodable` with a specific decoder. `Decodable` with a specific decoder.
For interned types instead of manually implementing `RefDecodable`, using a new For interned types instead of manually implementing `RefDecodable`, using a new
type wrapper, like `ty::Predicate` and manually implementing `Encodable` and type wrapper, like [`ty::Predicate`] and manually implementing `Encodable` and
`Decodable` may be simpler. `Decodable` may be simpler.
[`Decodable`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_serialize/trait.Decodable.html
[`Decoder`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_serialize/trait.Decoder.html
[`Encodable`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_serialize/trait.Encodable.html
[`Encoder`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_serialize/trait.Encoder.html
[`RefDecodable`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/codec/trait.RefDecodable.html
[`rustc_middle`]: https://doc.rust-lang.org/nightly/nightly-rustc/src/rustc_type_ir/codec.rs.html#21
[`ty::Predicate`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/predicate/struct.Predicate.html
[`TyCtxt`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.TyCtxt.html
[`TyDecodable`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_macros/derive.TyDecodable.html
[`TyDecoder`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/codec/trait.TyDecoder.html
[`TyEncodable`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_macros/derive.TyEncodable.html
[`TyEncoder`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/codec/trait.TyEncoder.html
[arena allocated types]: memory.md
[derives]: #derive-macros
[orphan rules]:https://doc.rust-lang.org/reference/items/implementations.html#orphan-rules
## Derive macros ## Derive macros
The `rustc_macros` crate defines various derives to help implement `Decodable` The [`rustc_macros`] crate defines various derives to help implement `Decodable`
and `Encodable`. and `Encodable`.
- The `Encodable` and `Decodable` macros generate implementations that apply to - The `Encodable` and `Decodable` macros generate implementations that apply to
all `Encoders` and `Decoders`. These should be used in crates that don't all `Encoders` and `Decoders`. These should be used in crates that don't
depend on `rustc_middle`, or that have to be serialized by a type that does depend on [`rustc_middle`], or that have to be serialized by a type that does
not implement `TyEncoder`. not implement `TyEncoder`.
- `MetadataEncodable` and `MetadataDecodable` generate implementations that - [`MetadataEncodable`] and [`MetadataDecodable`] generate implementations that
only allow decoding by [`rustc_metadata::rmeta::encoder::EncodeContext`] and only allow decoding by [`rustc_metadata::rmeta::encoder::EncodeContext`] and
[`rustc_metadata::rmeta::decoder::DecodeContext`]. These are used for types [`rustc_metadata::rmeta::decoder::DecodeContext`]. These are used for types
that contain `rustc_metadata::rmeta::Lazy*`. that contain [`rustc_metadata::rmeta::`]`Lazy*`.
- `TyEncodable` and `TyDecodable` generate implementation that apply to any - `TyEncodable` and `TyDecodable` generate implementation that apply to any
`TyEncoder` or `TyDecoder`. These should be used for types that are only `TyEncoder` or `TyDecoder`. These should be used for types that are only
serialized in crate metadata and/or the incremental cache, which is most serialized in crate metadata and/or the incremental cache, which is most
serializable types in `rustc_middle`. serializable types in `rustc_middle`.
[`MetadataDecodable`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_macros/derive.MetadataDecodable.html
[`MetadataEncodable`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_macros/derive.MetadataEncodable.html
[`rustc_macros`]: https://github.com/rust-lang/rust/tree/master/compiler/rustc_macros
[`rustc_metadata::rmeta::`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/rmeta/index.html
[`rustc_metadata::rmeta::decoder::DecodeContext`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/rmeta/decoder/struct.DecodeContext.html
[`rustc_metadata::rmeta::encoder::EncodeContext`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/rmeta/encoder/struct.EncodeContext.html
[`rustc_middle`]: https://github.com/rust-lang/rust/tree/master/compiler/rustc_middle
## Shorthands ## Shorthands
`Ty` can be deeply recursive, if each `Ty` was encoded naively then crate `Ty` can be deeply recursive, if each `Ty` was encoded naively then crate
@ -127,8 +157,9 @@ within the file being written is encoded instead. A similar scheme is used for
Crate metadata is initially loaded before the `TyCtxt<'tcx>` is created, so Crate metadata is initially loaded before the `TyCtxt<'tcx>` is created, so
some deserialization needs to be deferred from the initial loading of metadata. some deserialization needs to be deferred from the initial loading of metadata.
The [`LazyValue<T>`] type wraps the (relative) offset in the crate metadata where a The [`LazyValue<T>`] type wraps the (relative) offset in the crate metadata
`T` has been serialized. There are also some variants, [`LazyArray<T>`] and [`LazyTable<I, T>`]. where a `T` has been serialized. There are also some variants, [`LazyArray<T>`]
and [`LazyTable<I, T>`].
The `LazyArray<[T]>` and `LazyTable<I, T>` types provide some functionality over The `LazyArray<[T]>` and `LazyTable<I, T>` types provide some functionality over
`Lazy<Vec<T>>` and `Lazy<HashMap<I, T>>`: `Lazy<Vec<T>>` and `Lazy<HashMap<I, T>>`:
@ -138,8 +169,13 @@ The `LazyArray<[T]>` and `LazyTable<I, T>` types provide some functionality over
- Indexing into a `LazyTable<I, T>` does not require decoding entries other - Indexing into a `LazyTable<I, T>` does not require decoding entries other
than the one being read. than the one being read.
**note**: `LazyValue<T>` does not cache its value after being deserialized the first **note**: `LazyValue<T>` does not cache its value after being deserialized the
time. Instead the query system is the main way of caching these results. first time. Instead the query system its self is the main way of caching these
results.
[`LazyArray<T>`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/rmeta/struct.LazyValue.html
[`LazyTable<I, T>`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/rmeta/struct.LazyValue.html
[`LazyValue<T>`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/rmeta/struct.LazyValue.html
## Specialization ## Specialization
@ -147,19 +183,3 @@ A few types, most notably `DefId`, need to have different implementations for
different `Encoder`s. This is currently handled by ad-hoc specializations, for different `Encoder`s. This is currently handled by ad-hoc specializations, for
example: `DefId` has a `default` implementation of `Encodable<E>` and a example: `DefId` has a `default` implementation of `Encodable<E>` and a
specialized one for `Encodable<CacheEncoder>`. specialized one for `Encodable<CacheEncoder>`.
[`CrateInfo`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/struct.CrateInfo.html
[`LazyArray<T>`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/rmeta/struct.LazyValue.html
[`LazyTable<I, T>`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/rmeta/struct.LazyValue.html
[`LazyValue<T>`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/rmeta/struct.LazyValue.html
[`RefDecodable`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/codec/trait.RefDecodable.html
[`rustc_metadata::rmeta::decoder::DecodeContext`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/rmeta/decoder/struct.DecodeContext.html
[`rustc_metadata::rmeta::encoder::EncodeContext`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/rmeta/encoder/struct.EncodeContext.html
[`rustc_serialize`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_serialize/index.html
[`TyDecoder`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/codec/trait.TyDecoder.html
[`TyEncoder`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/codec/trait.TyEncoder.html
[arena allocated types]: memory.md
[AST]: the-parser.md
[derives]: #derive-macros
[persist incremental compilation results]: queries/incremental-compilation-in-detail.md#the-real-world-how-persistence-makes-everything-complicated
[serialize]: https://en.wikipedia.org/wiki/Serialization