rustc_middle/mir/
mono.rs

1use std::fmt;
2use std::hash::Hash;
3
4use rustc_ast::expand::autodiff_attrs::AutoDiffItem;
5use rustc_attr_data_structures::InlineAttr;
6use rustc_data_structures::base_n::{BaseNString, CASE_INSENSITIVE, ToBaseN};
7use rustc_data_structures::fingerprint::Fingerprint;
8use rustc_data_structures::fx::FxIndexMap;
9use rustc_data_structures::stable_hasher::{HashStable, StableHasher, ToStableHashKey};
10use rustc_data_structures::unord::UnordMap;
11use rustc_hashes::Hash128;
12use rustc_hir::ItemId;
13use rustc_hir::def_id::{CrateNum, DefId, DefIdSet, LOCAL_CRATE};
14use rustc_index::Idx;
15use rustc_macros::{HashStable, TyDecodable, TyEncodable};
16use rustc_query_system::ich::StableHashingContext;
17use rustc_session::config::OptLevel;
18use rustc_span::{Span, Symbol};
19use rustc_target::spec::SymbolVisibility;
20use tracing::debug;
21
22use crate::dep_graph::{DepNode, WorkProduct, WorkProductId};
23use crate::middle::codegen_fn_attrs::CodegenFnAttrFlags;
24use crate::ty::{self, GenericArgs, Instance, InstanceKind, SymbolName, Ty, TyCtxt};
25
26/// Describes how a monomorphization will be instantiated in object files.
27#[derive(PartialEq)]
28pub enum InstantiationMode {
29    /// There will be exactly one instance of the given MonoItem. It will have
30    /// external linkage so that it can be linked to from other codegen units.
31    GloballyShared {
32        /// In some compilation scenarios we may decide to take functions that
33        /// are typically `LocalCopy` and instead move them to `GloballyShared`
34        /// to avoid codegenning them a bunch of times. In this situation,
35        /// however, our local copy may conflict with other crates also
36        /// inlining the same function.
37        ///
38        /// This flag indicates that this situation is occurring, and informs
39        /// symbol name calculation that some extra mangling is needed to
40        /// avoid conflicts. Note that this may eventually go away entirely if
41        /// ThinLTO enables us to *always* have a globally shared instance of a
42        /// function within one crate's compilation.
43        may_conflict: bool,
44    },
45
46    /// Each codegen unit containing a reference to the given MonoItem will
47    /// have its own private copy of the function (with internal linkage).
48    LocalCopy,
49}
50
51#[derive(PartialEq, Eq, Clone, Copy, Debug, Hash, HashStable, TyEncodable, TyDecodable)]
52pub enum MonoItem<'tcx> {
53    Fn(Instance<'tcx>),
54    Static(DefId),
55    GlobalAsm(ItemId),
56}
57
58fn opt_incr_drop_glue_mode<'tcx>(tcx: TyCtxt<'tcx>, ty: Ty<'tcx>) -> InstantiationMode {
59    // Non-ADTs can't have a Drop impl. This case is mostly hit by closures whose captures require
60    // dropping.
61    let ty::Adt(adt_def, _) = ty.kind() else {
62        return InstantiationMode::LocalCopy;
63    };
64
65    // Types that don't have a direct Drop impl, but have fields that require dropping.
66    let Some(dtor) = adt_def.destructor(tcx) else {
67        // We use LocalCopy for drops of enums only; this code is inherited from
68        // https://github.com/rust-lang/rust/pull/67332 and the theory is that we get to optimize
69        // out code like drop_in_place(Option::None) before crate-local ThinLTO, which improves
70        // compile time. At the time of writing, simply removing this entire check does seem to
71        // regress incr-opt compile times. But it sure seems like a more sophisticated check could
72        // do better here.
73        if adt_def.is_enum() {
74            return InstantiationMode::LocalCopy;
75        } else {
76            return InstantiationMode::GloballyShared { may_conflict: true };
77        }
78    };
79
80    // We've gotten to a drop_in_place for a type that directly implements Drop.
81    // The drop glue is a wrapper for the Drop::drop impl, and we are an optimized build, so in an
82    // effort to coordinate with the mode that the actual impl will get, we make the glue also
83    // LocalCopy.
84    if tcx.cross_crate_inlinable(dtor.did) {
85        InstantiationMode::LocalCopy
86    } else {
87        InstantiationMode::GloballyShared { may_conflict: true }
88    }
89}
90
91impl<'tcx> MonoItem<'tcx> {
92    /// Returns `true` if the mono item is user-defined (i.e. not compiler-generated, like shims).
93    pub fn is_user_defined(&self) -> bool {
94        match *self {
95            MonoItem::Fn(instance) => matches!(instance.def, InstanceKind::Item(..)),
96            MonoItem::Static(..) | MonoItem::GlobalAsm(..) => true,
97        }
98    }
99
100    // Note: if you change how item size estimates work, you might need to
101    // change NON_INCR_MIN_CGU_SIZE as well.
102    pub fn size_estimate(&self, tcx: TyCtxt<'tcx>) -> usize {
103        match *self {
104            MonoItem::Fn(instance) => tcx.size_estimate(instance),
105            // Conservatively estimate the size of a static declaration or
106            // assembly item to be 1.
107            MonoItem::Static(_) | MonoItem::GlobalAsm(_) => 1,
108        }
109    }
110
111    pub fn is_generic_fn(&self) -> bool {
112        match self {
113            MonoItem::Fn(instance) => instance.args.non_erasable_generics().next().is_some(),
114            MonoItem::Static(..) | MonoItem::GlobalAsm(..) => false,
115        }
116    }
117
118    pub fn symbol_name(&self, tcx: TyCtxt<'tcx>) -> SymbolName<'tcx> {
119        match *self {
120            MonoItem::Fn(instance) => tcx.symbol_name(instance),
121            MonoItem::Static(def_id) => tcx.symbol_name(Instance::mono(tcx, def_id)),
122            MonoItem::GlobalAsm(item_id) => {
123                SymbolName::new(tcx, &format!("global_asm_{:?}", item_id.owner_id))
124            }
125        }
126    }
127
128    pub fn instantiation_mode(&self, tcx: TyCtxt<'tcx>) -> InstantiationMode {
129        // The case handling here is written in the same style as cross_crate_inlinable, we first
130        // handle the cases where we must use a particular instantiation mode, then cascade down
131        // through a sequence of heuristics.
132
133        // The first thing we do is detect MonoItems which we must instantiate exactly once in the
134        // whole program.
135
136        // Statics and global_asm! must be instantiated exactly once.
137        let instance = match *self {
138            MonoItem::Fn(instance) => instance,
139            MonoItem::Static(..) | MonoItem::GlobalAsm(..) => {
140                return InstantiationMode::GloballyShared { may_conflict: false };
141            }
142        };
143
144        // Similarly, the executable entrypoint must be instantiated exactly once.
145        if let Some((entry_def_id, _)) = tcx.entry_fn(()) {
146            if instance.def_id() == entry_def_id {
147                return InstantiationMode::GloballyShared { may_conflict: false };
148            }
149        }
150
151        // If the function is #[naked] or contains any other attribute that requires exactly-once
152        // instantiation:
153        let codegen_fn_attrs = tcx.codegen_fn_attrs(instance.def_id());
154        if codegen_fn_attrs.contains_extern_indicator()
155            || codegen_fn_attrs.flags.contains(CodegenFnAttrFlags::NAKED)
156        {
157            return InstantiationMode::GloballyShared { may_conflict: false };
158        }
159
160        // This is technically a heuristic even though it's in the "not a heuristic" part of
161        // instantiation mode selection.
162        // It is surely possible to untangle this; the root problem is that the way we instantiate
163        // InstanceKind other than Item is very complicated.
164        //
165        // The fallback case is to give everything else GloballyShared at OptLevel::No and
166        // LocalCopy at all other opt levels. This is a good default, except for one specific build
167        // configuration: Optimized incremental builds.
168        // In the current compiler architecture there is a fundamental tension between
169        // optimizations (which want big CGUs with as many things LocalCopy as possible) and
170        // incrementality (which wants small CGUs with as many things GloballyShared as possible).
171        // The heuristics implemented here do better than a completely naive approach in the
172        // compiler benchmark suite, but there is no reason to believe they are optimal.
173        if let InstanceKind::DropGlue(_, Some(ty)) = instance.def {
174            if tcx.sess.opts.optimize == OptLevel::No {
175                return InstantiationMode::GloballyShared { may_conflict: false };
176            }
177            if tcx.sess.opts.incremental.is_none() {
178                return InstantiationMode::LocalCopy;
179            }
180            return opt_incr_drop_glue_mode(tcx, ty);
181        }
182
183        // We need to ensure that we do not decide the InstantiationMode of an exported symbol is
184        // LocalCopy. Since exported symbols are computed based on the output of
185        // cross_crate_inlinable, we are beholden to our previous decisions.
186        //
187        // Note that just like above, this check for requires_inline is technically a heuristic
188        // even though it's in the "not a heuristic" part of instantiation mode selection.
189        if !tcx.cross_crate_inlinable(instance.def_id()) && !instance.def.requires_inline(tcx) {
190            return InstantiationMode::GloballyShared { may_conflict: false };
191        }
192
193        // Beginning of heuristics. The handling of link-dead-code and inline(always) are QoL only,
194        // the compiler should not crash and linkage should work, but codegen may be undesirable.
195
196        // -Clink-dead-code was given an unfortunate name; the point of the flag is to assist
197        // coverage tools which rely on having every function in the program appear in the
198        // generated code. If we select LocalCopy, functions which are not used because they are
199        // missing test coverage will disappear from such coverage reports, defeating the point.
200        // Note that -Cinstrument-coverage does not require such assistance from us, only coverage
201        // tools implemented without compiler support ironically require a special compiler flag.
202        if tcx.sess.link_dead_code() {
203            return InstantiationMode::GloballyShared { may_conflict: true };
204        }
205
206        // To ensure that #[inline(always)] can be inlined as much as possible, especially in unoptimized
207        // builds, we always select LocalCopy.
208        if codegen_fn_attrs.inline.always() {
209            return InstantiationMode::LocalCopy;
210        }
211
212        // #[inline(never)] functions in general are poor candidates for inlining and thus since
213        // LocalCopy generally increases code size for the benefit of optimizations from inlining,
214        // we want to give them GloballyShared codegen.
215        // The slight problem is that generic functions need to always support cross-crate
216        // compilation, so all previous stages of the compiler are obligated to treat generic
217        // functions the same as those that unconditionally get LocalCopy codegen. It's only when
218        // we get here that we can at least not codegen a #[inline(never)] generic function in all
219        // of our CGUs.
220        if let InlineAttr::Never = tcx.codegen_fn_attrs(instance.def_id()).inline
221            && self.is_generic_fn()
222        {
223            return InstantiationMode::GloballyShared { may_conflict: true };
224        }
225
226        // The fallthrough case is to generate LocalCopy for all optimized builds, and
227        // GloballyShared with conflict prevention when optimizations are disabled.
228        match tcx.sess.opts.optimize {
229            OptLevel::No => InstantiationMode::GloballyShared { may_conflict: true },
230            _ => InstantiationMode::LocalCopy,
231        }
232    }
233
234    pub fn explicit_linkage(&self, tcx: TyCtxt<'tcx>) -> Option<Linkage> {
235        let def_id = match *self {
236            MonoItem::Fn(ref instance) => instance.def_id(),
237            MonoItem::Static(def_id) => def_id,
238            MonoItem::GlobalAsm(..) => return None,
239        };
240
241        let codegen_fn_attrs = tcx.codegen_fn_attrs(def_id);
242        codegen_fn_attrs.linkage
243    }
244
245    /// Returns `true` if this instance is instantiable - whether it has no unsatisfied
246    /// predicates.
247    ///
248    /// In order to codegen an item, all of its predicates must hold, because
249    /// otherwise the item does not make sense. Type-checking ensures that
250    /// the predicates of every item that is *used by* a valid item *do*
251    /// hold, so we can rely on that.
252    ///
253    /// However, we codegen collector roots (reachable items) and functions
254    /// in vtables when they are seen, even if they are not used, and so they
255    /// might not be instantiable. For example, a programmer can define this
256    /// public function:
257    ///
258    ///     pub fn foo<'a>(s: &'a mut ()) where &'a mut (): Clone {
259    ///         <&mut () as Clone>::clone(&s);
260    ///     }
261    ///
262    /// That function can't be codegened, because the method `<&mut () as Clone>::clone`
263    /// does not exist. Luckily for us, that function can't ever be used,
264    /// because that would require for `&'a mut (): Clone` to hold, so we
265    /// can just not emit any code, or even a linker reference for it.
266    ///
267    /// Similarly, if a vtable method has such a signature, and therefore can't
268    /// be used, we can just not emit it and have a placeholder (a null pointer,
269    /// which will never be accessed) in its place.
270    pub fn is_instantiable(&self, tcx: TyCtxt<'tcx>) -> bool {
271        debug!("is_instantiable({:?})", self);
272        let (def_id, args) = match *self {
273            MonoItem::Fn(ref instance) => (instance.def_id(), instance.args),
274            MonoItem::Static(def_id) => (def_id, GenericArgs::empty()),
275            // global asm never has predicates
276            MonoItem::GlobalAsm(..) => return true,
277        };
278
279        !tcx.instantiate_and_check_impossible_predicates((def_id, &args))
280    }
281
282    pub fn local_span(&self, tcx: TyCtxt<'tcx>) -> Option<Span> {
283        match *self {
284            MonoItem::Fn(Instance { def, .. }) => def.def_id().as_local(),
285            MonoItem::Static(def_id) => def_id.as_local(),
286            MonoItem::GlobalAsm(item_id) => Some(item_id.owner_id.def_id),
287        }
288        .map(|def_id| tcx.def_span(def_id))
289    }
290
291    // Only used by rustc_codegen_cranelift
292    pub fn codegen_dep_node(&self, tcx: TyCtxt<'tcx>) -> DepNode {
293        crate::dep_graph::make_compile_mono_item(tcx, self)
294    }
295
296    /// Returns the item's `CrateNum`
297    pub fn krate(&self) -> CrateNum {
298        match self {
299            MonoItem::Fn(instance) => instance.def_id().krate,
300            MonoItem::Static(def_id) => def_id.krate,
301            MonoItem::GlobalAsm(..) => LOCAL_CRATE,
302        }
303    }
304
305    /// Returns the item's `DefId`
306    pub fn def_id(&self) -> DefId {
307        match *self {
308            MonoItem::Fn(Instance { def, .. }) => def.def_id(),
309            MonoItem::Static(def_id) => def_id,
310            MonoItem::GlobalAsm(item_id) => item_id.owner_id.to_def_id(),
311        }
312    }
313}
314
315impl<'tcx> fmt::Display for MonoItem<'tcx> {
316    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
317        match *self {
318            MonoItem::Fn(instance) => write!(f, "fn {instance}"),
319            MonoItem::Static(def_id) => {
320                write!(f, "static {}", Instance::new(def_id, GenericArgs::empty()))
321            }
322            MonoItem::GlobalAsm(..) => write!(f, "global_asm"),
323        }
324    }
325}
326
327impl ToStableHashKey<StableHashingContext<'_>> for MonoItem<'_> {
328    type KeyType = Fingerprint;
329
330    fn to_stable_hash_key(&self, hcx: &StableHashingContext<'_>) -> Self::KeyType {
331        let mut hasher = StableHasher::new();
332        self.hash_stable(&mut hcx.clone(), &mut hasher);
333        hasher.finish()
334    }
335}
336
337#[derive(Debug, HashStable, Copy, Clone)]
338pub struct MonoItemPartitions<'tcx> {
339    pub codegen_units: &'tcx [CodegenUnit<'tcx>],
340    pub all_mono_items: &'tcx DefIdSet,
341    pub autodiff_items: &'tcx [AutoDiffItem],
342}
343
344#[derive(Debug, HashStable)]
345pub struct CodegenUnit<'tcx> {
346    /// A name for this CGU. Incremental compilation requires that
347    /// name be unique amongst **all** crates. Therefore, it should
348    /// contain something unique to this crate (e.g., a module path)
349    /// as well as the crate name and disambiguator.
350    name: Symbol,
351    items: FxIndexMap<MonoItem<'tcx>, MonoItemData>,
352    size_estimate: usize,
353    primary: bool,
354    /// True if this is CGU is used to hold code coverage information for dead code,
355    /// false otherwise.
356    is_code_coverage_dead_code_cgu: bool,
357}
358
359/// Auxiliary info about a `MonoItem`.
360#[derive(Copy, Clone, PartialEq, Debug, HashStable)]
361pub struct MonoItemData {
362    /// A cached copy of the result of `MonoItem::instantiation_mode`, where
363    /// `GloballyShared` maps to `false` and `LocalCopy` maps to `true`.
364    pub inlined: bool,
365
366    pub linkage: Linkage,
367    pub visibility: Visibility,
368
369    /// A cached copy of the result of `MonoItem::size_estimate`.
370    pub size_estimate: usize,
371}
372
373/// Specifies the linkage type for a `MonoItem`.
374///
375/// See <https://llvm.org/docs/LangRef.html#linkage-types> for more details about these variants.
376#[derive(Copy, Clone, PartialEq, Debug, TyEncodable, TyDecodable, HashStable)]
377pub enum Linkage {
378    External,
379    AvailableExternally,
380    LinkOnceAny,
381    LinkOnceODR,
382    WeakAny,
383    WeakODR,
384    Internal,
385    ExternalWeak,
386    Common,
387}
388
389/// Specifies the symbol visibility with regards to dynamic linking.
390///
391/// Visibility doesn't have any effect when linkage is internal.
392///
393/// DSO means dynamic shared object, that is a dynamically linked executable or dylib.
394#[derive(Copy, Clone, PartialEq, Debug, HashStable)]
395pub enum Visibility {
396    /// Export the symbol from the DSO and apply overrides of the symbol by outside DSOs to within
397    /// the DSO if the object file format supports this.
398    Default,
399    /// Hide the symbol outside of the defining DSO even when external linkage is used to export it
400    /// from the object file.
401    Hidden,
402    /// Export the symbol from the DSO, but don't apply overrides of the symbol by outside DSOs to
403    /// within the DSO. Equivalent to default visibility with object file formats that don't support
404    /// overriding exported symbols by another DSO.
405    Protected,
406}
407
408impl From<SymbolVisibility> for Visibility {
409    fn from(value: SymbolVisibility) -> Self {
410        match value {
411            SymbolVisibility::Hidden => Visibility::Hidden,
412            SymbolVisibility::Protected => Visibility::Protected,
413            SymbolVisibility::Interposable => Visibility::Default,
414        }
415    }
416}
417
418impl<'tcx> CodegenUnit<'tcx> {
419    #[inline]
420    pub fn new(name: Symbol) -> CodegenUnit<'tcx> {
421        CodegenUnit {
422            name,
423            items: Default::default(),
424            size_estimate: 0,
425            primary: false,
426            is_code_coverage_dead_code_cgu: false,
427        }
428    }
429
430    pub fn name(&self) -> Symbol {
431        self.name
432    }
433
434    pub fn set_name(&mut self, name: Symbol) {
435        self.name = name;
436    }
437
438    pub fn is_primary(&self) -> bool {
439        self.primary
440    }
441
442    pub fn make_primary(&mut self) {
443        self.primary = true;
444    }
445
446    pub fn items(&self) -> &FxIndexMap<MonoItem<'tcx>, MonoItemData> {
447        &self.items
448    }
449
450    pub fn items_mut(&mut self) -> &mut FxIndexMap<MonoItem<'tcx>, MonoItemData> {
451        &mut self.items
452    }
453
454    pub fn is_code_coverage_dead_code_cgu(&self) -> bool {
455        self.is_code_coverage_dead_code_cgu
456    }
457
458    /// Marks this CGU as the one used to contain code coverage information for dead code.
459    pub fn make_code_coverage_dead_code_cgu(&mut self) {
460        self.is_code_coverage_dead_code_cgu = true;
461    }
462
463    pub fn mangle_name(human_readable_name: &str) -> BaseNString {
464        let mut hasher = StableHasher::new();
465        human_readable_name.hash(&mut hasher);
466        let hash: Hash128 = hasher.finish();
467        hash.as_u128().to_base_fixed_len(CASE_INSENSITIVE)
468    }
469
470    pub fn compute_size_estimate(&mut self) {
471        // The size of a codegen unit as the sum of the sizes of the items
472        // within it.
473        self.size_estimate = self.items.values().map(|data| data.size_estimate).sum();
474    }
475
476    /// Should only be called if [`compute_size_estimate`] has previously been called.
477    ///
478    /// [`compute_size_estimate`]: Self::compute_size_estimate
479    #[inline]
480    pub fn size_estimate(&self) -> usize {
481        // Items are never zero-sized, so if we have items the estimate must be
482        // non-zero, unless we forgot to call `compute_size_estimate` first.
483        assert!(self.items.is_empty() || self.size_estimate != 0);
484        self.size_estimate
485    }
486
487    pub fn contains_item(&self, item: &MonoItem<'tcx>) -> bool {
488        self.items().contains_key(item)
489    }
490
491    pub fn work_product_id(&self) -> WorkProductId {
492        WorkProductId::from_cgu_name(self.name().as_str())
493    }
494
495    pub fn previous_work_product(&self, tcx: TyCtxt<'_>) -> WorkProduct {
496        let work_product_id = self.work_product_id();
497        tcx.dep_graph
498            .previous_work_product(&work_product_id)
499            .unwrap_or_else(|| panic!("Could not find work-product for CGU `{}`", self.name()))
500    }
501
502    pub fn items_in_deterministic_order(
503        &self,
504        tcx: TyCtxt<'tcx>,
505    ) -> Vec<(MonoItem<'tcx>, MonoItemData)> {
506        // The codegen tests rely on items being process in the same order as
507        // they appear in the file, so for local items, we sort by node_id first
508        #[derive(PartialEq, Eq, PartialOrd, Ord)]
509        struct ItemSortKey<'tcx>(Option<usize>, SymbolName<'tcx>);
510
511        fn item_sort_key<'tcx>(tcx: TyCtxt<'tcx>, item: MonoItem<'tcx>) -> ItemSortKey<'tcx> {
512            ItemSortKey(
513                match item {
514                    MonoItem::Fn(ref instance) => {
515                        match instance.def {
516                            // We only want to take HirIds of user-defined
517                            // instances into account. The others don't matter for
518                            // the codegen tests and can even make item order
519                            // unstable.
520                            InstanceKind::Item(def) => def.as_local().map(Idx::index),
521                            InstanceKind::VTableShim(..)
522                            | InstanceKind::ReifyShim(..)
523                            | InstanceKind::Intrinsic(..)
524                            | InstanceKind::FnPtrShim(..)
525                            | InstanceKind::Virtual(..)
526                            | InstanceKind::ClosureOnceShim { .. }
527                            | InstanceKind::ConstructCoroutineInClosureShim { .. }
528                            | InstanceKind::DropGlue(..)
529                            | InstanceKind::CloneShim(..)
530                            | InstanceKind::ThreadLocalShim(..)
531                            | InstanceKind::FnPtrAddrShim(..)
532                            | InstanceKind::AsyncDropGlueCtorShim(..) => None,
533                        }
534                    }
535                    MonoItem::Static(def_id) => def_id.as_local().map(Idx::index),
536                    MonoItem::GlobalAsm(item_id) => Some(item_id.owner_id.def_id.index()),
537                },
538                item.symbol_name(tcx),
539            )
540        }
541
542        let mut items: Vec<_> = self.items().iter().map(|(&i, &data)| (i, data)).collect();
543        items.sort_by_cached_key(|&(i, _)| item_sort_key(tcx, i));
544        items
545    }
546
547    pub fn codegen_dep_node(&self, tcx: TyCtxt<'tcx>) -> DepNode {
548        crate::dep_graph::make_compile_codegen_unit(tcx, self.name())
549    }
550}
551
552impl ToStableHashKey<StableHashingContext<'_>> for CodegenUnit<'_> {
553    type KeyType = String;
554
555    fn to_stable_hash_key(&self, _: &StableHashingContext<'_>) -> Self::KeyType {
556        // Codegen unit names are conceptually required to be stable across
557        // compilation session so that object file names match up.
558        self.name.to_string()
559    }
560}
561
562pub struct CodegenUnitNameBuilder<'tcx> {
563    tcx: TyCtxt<'tcx>,
564    cache: UnordMap<CrateNum, String>,
565}
566
567impl<'tcx> CodegenUnitNameBuilder<'tcx> {
568    pub fn new(tcx: TyCtxt<'tcx>) -> Self {
569        CodegenUnitNameBuilder { tcx, cache: Default::default() }
570    }
571
572    /// CGU names should fulfill the following requirements:
573    /// - They should be able to act as a file name on any kind of file system
574    /// - They should not collide with other CGU names, even for different versions
575    ///   of the same crate.
576    ///
577    /// Consequently, we don't use special characters except for '.' and '-' and we
578    /// prefix each name with the crate-name and crate-disambiguator.
579    ///
580    /// This function will build CGU names of the form:
581    ///
582    /// ```text
583    /// <crate-name>.<crate-disambiguator>[-in-<local-crate-id>](-<component>)*[.<special-suffix>]
584    /// <local-crate-id> = <local-crate-name>.<local-crate-disambiguator>
585    /// ```
586    ///
587    /// The '.' before `<special-suffix>` makes sure that names with a special
588    /// suffix can never collide with a name built out of regular Rust
589    /// identifiers (e.g., module paths).
590    pub fn build_cgu_name<I, C, S>(
591        &mut self,
592        cnum: CrateNum,
593        components: I,
594        special_suffix: Option<S>,
595    ) -> Symbol
596    where
597        I: IntoIterator<Item = C>,
598        C: fmt::Display,
599        S: fmt::Display,
600    {
601        let cgu_name = self.build_cgu_name_no_mangle(cnum, components, special_suffix);
602
603        if self.tcx.sess.opts.unstable_opts.human_readable_cgu_names {
604            cgu_name
605        } else {
606            Symbol::intern(&CodegenUnit::mangle_name(cgu_name.as_str()))
607        }
608    }
609
610    /// Same as `CodegenUnit::build_cgu_name()` but will never mangle the
611    /// resulting name.
612    pub fn build_cgu_name_no_mangle<I, C, S>(
613        &mut self,
614        cnum: CrateNum,
615        components: I,
616        special_suffix: Option<S>,
617    ) -> Symbol
618    where
619        I: IntoIterator<Item = C>,
620        C: fmt::Display,
621        S: fmt::Display,
622    {
623        use std::fmt::Write;
624
625        let mut cgu_name = String::with_capacity(64);
626
627        // Start out with the crate name and disambiguator
628        let tcx = self.tcx;
629        let crate_prefix = self.cache.entry(cnum).or_insert_with(|| {
630            // Whenever the cnum is not LOCAL_CRATE we also mix in the
631            // local crate's ID. Otherwise there can be collisions between CGUs
632            // instantiating stuff for upstream crates.
633            let local_crate_id = if cnum != LOCAL_CRATE {
634                let local_stable_crate_id = tcx.stable_crate_id(LOCAL_CRATE);
635                format!("-in-{}.{:08x}", tcx.crate_name(LOCAL_CRATE), local_stable_crate_id)
636            } else {
637                String::new()
638            };
639
640            let stable_crate_id = tcx.stable_crate_id(LOCAL_CRATE);
641            format!("{}.{:08x}{}", tcx.crate_name(cnum), stable_crate_id, local_crate_id)
642        });
643
644        write!(cgu_name, "{crate_prefix}").unwrap();
645
646        // Add the components
647        for component in components {
648            write!(cgu_name, "-{component}").unwrap();
649        }
650
651        if let Some(special_suffix) = special_suffix {
652            // We add a dot in here so it cannot clash with anything in a regular
653            // Rust identifier
654            write!(cgu_name, ".{special_suffix}").unwrap();
655        }
656
657        Symbol::intern(&cgu_name)
658    }
659}
660
661/// See module-level docs of `rustc_monomorphize::collector` on some context for "mentioned" items.
662#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, HashStable)]
663pub enum CollectionMode {
664    /// Collect items that are used, i.e., actually needed for codegen.
665    ///
666    /// Which items are used can depend on optimization levels, as MIR optimizations can remove
667    /// uses.
668    UsedItems,
669    /// Collect items that are mentioned. The goal of this mode is that it is independent of
670    /// optimizations: the set of "mentioned" items is computed before optimizations are run.
671    ///
672    /// The exact contents of this set are *not* a stable guarantee. (For instance, it is currently
673    /// computed after drop-elaboration. If we ever do some optimizations even in debug builds, we
674    /// might decide to run them before computing mentioned items.) The key property of this set is
675    /// that it is optimization-independent.
676    MentionedItems,
677}