Derive Macros, Shorthands, Lazy Values, and Specialization

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 implemented for any type. The `TyDecodable` macro will call `RefDecodable` to decode references, but various generic code needs types to actually be `Decodable` with a specific decoder. For interned types instead of manually implementing `RefDecodable`, using a new type wrapper, like [`ty::Predicate`] and manually implementing `Encodable` and `Decodable` may be simpler. ## Derive macros The [`rustc_macros`] crate defines various derives to help implement `Decodable` and `Encodable`. - The `Encodable` and `Decodable` macros generate implementations that apply to 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 not implement `TyEncoder`. - [`MetadataEncodable`] and [`MetadataDecodable`] generate implementations that only allow decoding by [`rustc_metadata::rmeta::encoder::EncodeContext`] and [`rustc_metadata::rmeta::decoder::DecodeContext`]. These are used for types that contain [`rustc_metadata::rmeta::`]`Lazy*`. - `TyEncodable` and `TyDecodable` generate implementation that apply to any `TyEncoder` or `TyDecoder`. These should be used for types that are only serialized in crate metadata and/or the incremental cache, which is most serializable types in `rustc_middle`. ## Shorthands `Ty` can be deeply recursive, if each `Ty` was encoded naively then crate metadata would be very large. To handle this, each `TyEncoder` has a cache of locations in its output where it has serialized types. If a type being encoded is in the cache, then instead of serializing the type as usual, the byte offset within the file being written is encoded instead. A similar scheme is used for `ty::Predicate`. ## `LazyValue<T>` Crate metadata is initially loaded before the `TyCtxt<'tcx>` is created, so 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 `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 `Lazy<Vec<T>>` and `Lazy<HashMap<I, T>>`: - It's possible to encode a `LazyArray<T>` directly from an `Iterator`, without first collecting into a `Vec<T>`. - Indexing into a `LazyTable<I, T>` does not require decoding entries other than the one being read. **note**: `LazyValue<T>` does not cache its value after being deserialized the first time. Instead the query system itself is the main way of caching these results. ## Specialization A few types, most notably `DefId`, need to have different implementations for different `Encoder`s. This is currently handled by ad-hoc specializations, for example: `DefId` has a `default` implementation of `Encodable<E>` and a specialized one for `Encodable<CacheEncoder>`.

This section covers derive macros in `rustc_macros` for `Decodable` and `Encodable`, including `MetadataEncodable`/`Decodable` for `Lazy*` types and `TyEncodable`/`Decodable` for types serialized in metadata or the incremental cache. It discusses shorthands like caching type locations in `TyEncoder` to reduce metadata size. `LazyValue<T>` defers deserialization until the `TyCtxt` is created and doesn't cache values after deserialization. `LazyArray<T>` and `LazyTable<I, T>` provide functionality over `Lazy<Vec<T>>` and `Lazy<HashMap<I, T>>`. Finally, it touches on ad-hoc specialization for types like `DefId` to provide different `Encodable` implementations for different encoders.