Crate rustc_type_ir

Expand description

This crate is an abstraction layer, shared between rustc and rust-analyzer, to help with the overlapping responsibilities (like type inference and trait solving), reduce duplication, and maintain consistent behavior between the two implementations.

It defines fundamental interfaces for types, predicates, and the context required by the next trait solver.

Both rustc and rust-analyzer immplement these traits for their own concrete implementations, and rustc_next_trait_solver is written to be generic over these abstractions.

In addition to these interfaces, it also contains components built on top of the abstraction layer, for example elaboration logic, and the search graph machinery used by the solver, as well as items that do not need compiler-specific implementations.

Note that rust-analyzer is built with a stable compiler, while rustc uses unstable features, so this crate and some of its dependencies need to separate unstable code under the nightly feature.

There are more details available in a dedicated dev-guide chapter.

Re-exports§

pub use AliasTyKind::*;
pub use InferTy::*;
pub use RegionKind::*;
pub use TyKind::*;
pub use Variance::*;
pub use sty::*;

Modules§

binder 🔒
canonical 🔒
const_kind 🔒
data_structures
elaborate
error
fast_reject
flags 🔒
fold 🔒: A folding traversal mechanism for complex data structures that contain type information.
generic_arg 🔒
generic_visit 🔒: Special visiting used by rust-analyzer only.
infer_ctxt 🔒
inherent: Set of traits which are used to emulate the inherent impls that are present in rustc_middle. It is customary to glob-import rustc_type_ir::inherent::* to bring all of these traits into scope when programming in interner-agnostic settings, and to avoid importing any of these directly elsewhere (i.e. specify the full path for an implementation downstream).
intern
interner 🔒
ir_print
lang_items
lift
macros 🔒
opaque_ty 🔒
outlives: The outlives relation T: 'a or 'a: 'b. This code frequently refers to rules defined in RFC 1214 (OutlivesFooBar), so see that RFC for reference.
pattern 🔒
predicate 🔒
predicate_kind 🔒
region_constraint: The bulk of the logic for implementing -Zassumptions-on-binders
region_kind 🔒
relate
search_graph: The search graph is responsible for caching and cycle detection in the trait solver. Making sure that caching doesn’t result in soundness bugs or unstable query results is very challenging and makes this one of the most-involved self-contained components of the compiler.
serialize 🔒
solve
sty
term_kind 🔒
ty 🔒
ty_info 🔒
ty_kind 🔒
universe 🔒
unnormalized 🔒
upcast 🔒
visit 🔒: A visiting traversal mechanism for complex data structures that contain type information.
walk: An iterator over the type substructure. WARNING: this does not keep track of the region depth.

Macros§

TrivialTypeTraversalImpls: Used for types that are Copy and which do not care arena allocated data (i.e., don’t need to be folded).
try_visit
walk_visitable_list

Structs§

Alias: Represents an alias of a type, constant, or other term-like item.
Binder: Binder is a binder for higher-ranked lifetimes or types. It is part of the compiler’s representation for things like for<'a> Fn(&'a isize) (which would be represented by the type PolyTraitRef == Binder<I, TraitRef>).
BoundConst
BoundRegion
BoundTy
BoundVar
Canonical: A “canonicalized” type V is one where all free inference variables have been rewritten to “canonical vars”. These are numbered starting from 0 in order of first appearance.
CanonicalParamEnvCache
CanonicalParamEnvCacheEntry
CanonicalQueryInput
CanonicalVarValues: A set of values corresponding to the canonical variables from some Canonical. You can give these values to canonical_value.instantiate to instantiate them into the canonical value at the right places.
CanonicalizerState: State used and modified by a canonicalizer during canonicalization. To avoid many allocations, this state is reused by many canonicalizers from a single InferCtxt.
ClosureArgs: A closure can be modeled as a struct that looks like:
ClosureArgsParts: Struct returned by split().
CoercePredicate: Encodes that we have to coerce from the a type to the b type.
ConstVid: A const variable ID.
CoroutineArgs: Similar to ClosureArgs; see the above documentation for more.
CoroutineArgsParts
CoroutineClosureArgs
CoroutineClosureArgsParts: See docs for explanation of how each argument is used.
CoroutineClosureSignature
CoroutineWitnessTypes
DebruijnIndex: A De Bruijn index is a standard means of representing regions (and perhaps later types) in a higher-ranked setting. In particular, imagine a type like this:
EarlyBinder: Similar to Binder except that it tracks early bound generics, i.e. struct Foo<T>(T) needs T instantiated immediately. This type primarily exists to avoid forgetting to call instantiate.
EarlyBinderIter
ExistentialProjection: A ProjectionClause for an ExistentialTraitRef.
ExistentialTraitRef: An existential reference to a trait where the self type Self is erased.
FieldInfo
FlagComputation
FloatVid: A floating-point (f32 or f64) type variable ID.
FnHeader
FnSig
FnSigKind: Contains the packed non-type fields of a function signature.
FnSigTys
GenSig
HostEffectClause
IntVid: An integral (u32, i32, usize, etc.) type variable ID.
IterIdentityCopied
IterInstantiated
IterInstantiatedCopied
MayBeErased
NormalizesTo: Used by the new solver to normalize an alias. This always expects the term to be an unconstrained inference variable which is used as the output.
OpaqueTypeKey
OutlivesClause: A: 'region
Placeholder: The “placeholder index” fully defines a placeholder region, type, or const. Placeholders are identified by both a universe, as well as a name residing within that universe. Distinct bound regions/types/consts within the same universe simply have an unknown relationship to one
ProjectionClause: This kind of predicate has no direct correspondent in the syntax, but it roughly corresponds to the syntactic forms:
RegionEqPredicate: 'a == 'b. For the rationale behind having this instead of a pair of bidirectional 'a: 'b and 'b: 'a, see this discusstion on Zulip.
RegionFolder: Folds over the substructure of a type, visiting its component types and all regions that occur free within it.
RegionVid: A region variable ID.
SubtypePredicate: Encodes that a must be a subtype of b. The a_is_expected flag indicates whether the a type is the type that we should label as “expected” when presenting user diagnostics.
TraitClause
TraitRef: A complete reference to a trait.
TyVid: A type variable ID.
TypeAndMut
TypeFlags: Flags that we track on types. These flags are propagated upwards through the type during type construction, so that we can quickly check whether the type has various kinds of types in it without recursing over the type itself.
TypingModeEqWrapper: We want to highly discourage using equality checks on typing modes. Instead you should match, exhaustively, so when we ever modify the enum we get a compile error. Only use TypingModeEqWrapper when you really really really have to. Prefer unwrapping TypingModeEqWrapper in apis that should return a TypingMode whenever possible, and if you ever get an TypingModeEqWrapper, prefer unwrapping it and matching on it exhaustively.
UniverseIndex: “Universes” are used during type- and trait-checking in the presence of for<..> binders to control what sets of names are visible. Universes are arranged into a tree: the root universe contains names that are always visible. Each child then adds a new set of names that are visible, in addition to those of its parent. We say that the child universe “extends” the parent universe with new names.
Unnormalized: A wrapper for values that need normalization.
UnsafeBinderInner
ValidateBoundVars
WithCachedTypeInfo: A helper type that you can wrap round your own type in order to automatically cache the type flags and debruijn index on creation and not recompute it whenever the information is needed.

Enums§

AliasConstKind: AliasConstKind is extremely similar to AliasTyKind, and likely should be reasoned about and handled in very similar ways. The documentation for AliasTyKind/etc. may be helpful when learning about AliasConstKind.
AliasTermKind
AliasTyKind
AnonConstKind
BoundConstness
BoundRegionKind
BoundTyKind
BoundVarIndexKind: Okay, we do something fun for Bound types/regions/consts: Specifically, we distinguish between canonically bound things and for<> bound things. And, really, it comes down to caching during canonicalization and instantiation.
BoundVariableKind
CanonicalVarKind: Information about a canonical variable that is included with the canonical value. This is sufficient information for code to create a copy of the canonical value in some other inference context, with fresh inference variables replacing the canonical values.
CantBeErased
ClauseKind: A clause is something that can appear in where bounds or be inferred by implied bounds.
ClausePolarity: Polarity for a trait clause.
ClosureKind: Represents the various closure traits in the language. This will determine the type of the environment (self, in the desugaring) argument that the closure expects.
ConstKind: Represents a constant in Rust.
ExistentialPredicate
FloatTy
FloatVarValue
GenericArgKind
ImplPolarity
InferConst: An inference variable for a const, for use in const generics.
InferTy: A placeholder for a type that hasn’t been inferred yet.
IntTy
IntVarValue
IsRigid: Whether an alias type is rigid or potentially normalizeable.
Movability: The movability of a coroutine / closure literal: whether a coroutine contains self-references, causing it to be !Unpin.
Mutability
PatternKind
Pinnedness
PredicateKind
RegionConstraint
RegionKind: Representation of regions. Note that the NLL checker uses a distinct representation of regions. For this reason, it internally replaces all the regions with inference variables – the index of the variable is then used to index into internal NLL data structures. See rustc_const_eval::borrow_check module for more information.
SplattedArgIndexError: Error type for splatted argument index errors.
TermKind
TyKind: Defines the kinds of types used by the type system.
TypingMode: The current typing mode of an inference context. We unfortunately have some slightly different typing rules depending on the current context. See the doc comment for each variant for how and why they are used.
UintTy
ValTreeKind: This datastructure is used to represent the value of constants used in the type system.
Variance

Constants§

INNERMOST

Traits§

CollectAndApply: Imagine you have a function F: FnOnce(&[T]) -> R, plus an iterator iter that produces T items. You could combine them with f(&iter.collect::<Vec<_>>()), but this requires allocating memory for the Vec.
FallibleTypeFolder: This trait is implemented for every folding traversal. There is a fold method defined for every type of interest. Each such method has a default that does an “identity” fold.
Flags
GenericTypeVisitable: This trait is implemented for every type that can be visited, providing the skeleton of the traversal.
InferCtxtLike: InferCtxtLike is one of the two traits abstracting over the InferCtxt, which had to be split due to coherence reasons:
Interner: The central trait in the shared abstraction layer, specifying all implementation-specific details for rustc and rust-analyzer.
InternerDecoder: A decoder that can reconstruct interned type IR values by supplying the interner that owns the decoded data.
LiftInto: An interner whose associated types can be lifted into another interner J.
TypeFoldable: This trait is implemented for every type that can be folded, providing the skeleton of the traversal.
TypeFolder: This trait is implemented for every infallible folding traversal. There is a fold method defined for every type of interest. Each such method has a default that does an “identity” fold. Implementations of these methods often fall back to a super_fold_with method if the primary argument doesn’t satisfy a particular condition.
TypeSuperFoldable
TypeSuperVisitable
TypeVisitable: This trait is implemented for every type that can be visited, providing the skeleton of the traversal.
TypeVisitableExt
TypeVisitor: This trait is implemented for every visiting traversal. There is a visit method defined for every type of interest. Each such method has a default that recurses into the type’s fields in a non-custom fashion.
TypingModeErasedStatus
Upcast: An Into-like trait that takes TyCtxt to perform interner-specific transformations.
UpcastFrom: A From-like trait that takes TyCtxt to perform interner-specific transformations.
VisitorResult: Similar to the Try trait, but also implemented for ().

Functions§

debug_bound_var
eager_resolve_vars: Resolves ty, region, and const vars to their inferred values or their root vars.
fold_regions
max_universe: The largest universe a variable or placeholder was from in t
max_universe_of_infer_vars: The largest universe a variable was from in t
max_universe_of_placeholders: The largest universe a placeholder was from in t
may_use_unstable_feature
set_aliases_to_non_rigid: This function should ideally only be used if either the TypingMode or the ParamEnv differs from the environment the aliases were normalized in.
set_aliases_to_rigid
set_opaques_to_non_rigid
set_type_aliases_to_rigid
shift_region
shift_vars

Type Aliases§

AliasConst
AliasTerm
AliasTy
FreeAliasTy
InherentAliasTy
OpaqueAliasTy
PlaceholderConst
PlaceholderRegion
PlaceholderType
ProjectionAliasTy