1 //! The Rust Linkage Model and Symbol Names
2 //! =======================================
4 //! The semantic model of Rust linkage is, broadly, that "there's no global
5 //! namespace" between crates. Our aim is to preserve the illusion of this
6 //! model despite the fact that it's not *quite* possible to implement on
7 //! modern linkers. We initially didn't use system linkers at all, but have
8 //! been convinced of their utility.
10 //! There are a few issues to handle:
12 //! - Linkers operate on a flat namespace, so we have to flatten names.
13 //! We do this using the C++ namespace-mangling technique. Foo::bar
16 //! - Symbols for distinct items with the same *name* need to get different
17 //! linkage-names. Examples of this are monomorphizations of functions or
18 //! items within anonymous scopes that end up having the same path.
20 //! - Symbols in different crates but with same names "within" the crate need
21 //! to get different linkage-names.
23 //! - Symbol names should be deterministic: Two consecutive runs of the
24 //! compiler over the same code base should produce the same symbol names for
27 //! - Symbol names should not depend on any global properties of the code base,
28 //! so that small modifications to the code base do not result in all symbols
29 //! changing. In previous versions of the compiler, symbol names incorporated
30 //! the SVH (Stable Version Hash) of the crate. This scheme turned out to be
31 //! infeasible when used in conjunction with incremental compilation because
32 //! small code changes would invalidate all symbols generated previously.
34 //! - Even symbols from different versions of the same crate should be able to
35 //! live next to each other without conflict.
37 //! In order to fulfill the above requirements the following scheme is used by
40 //! The main tool for avoiding naming conflicts is the incorporation of a 64-bit
41 //! hash value into every exported symbol name. Anything that makes a difference
42 //! to the symbol being named, but does not show up in the regular path needs to
43 //! be fed into this hash:
45 //! - Different monomorphizations of the same item have the same path but differ
46 //! in their concrete type parameters, so these parameters are part of the
47 //! data being digested for the symbol hash.
49 //! - Rust allows items to be defined in anonymous scopes, such as in
50 //! `fn foo() { { fn bar() {} } { fn bar() {} } }`. Both `bar` functions have
51 //! the path `foo::bar`, since the anonymous scopes do not contribute to the
52 //! path of an item. The compiler already handles this case via so-called
53 //! disambiguating `DefPaths` which use indices to distinguish items with the
54 //! same name. The DefPaths of the functions above are thus `foo[0]::bar[0]`
55 //! and `foo[0]::bar[1]`. In order to incorporate this disambiguation
56 //! information into the symbol name too, these indices are fed into the
57 //! symbol hash, so that the above two symbols would end up with different
60 //! The two measures described above suffice to avoid intra-crate conflicts. In
61 //! order to also avoid inter-crate conflicts two more measures are taken:
63 //! - The name of the crate containing the symbol is prepended to the symbol
64 //! name, i.e., symbols are "crate qualified". For example, a function `foo` in
65 //! module `bar` in crate `baz` would get a symbol name like
66 //! `baz::bar::foo::{hash}` instead of just `bar::foo::{hash}`. This avoids
67 //! simple conflicts between functions from different crates.
69 //! - In order to be able to also use symbols from two versions of the same
70 //! crate (which naturally also have the same name), a stronger measure is
71 //! required: The compiler accepts an arbitrary "disambiguator" value via the
72 //! `-C metadata` command-line argument. This disambiguator is then fed into
73 //! the symbol hash of every exported item. Consequently, the symbols in two
74 //! identical crates but with different disambiguators are not in conflict
75 //! with each other. This facility is mainly intended to be used by build
78 //! A note on symbol name stability
79 //! -------------------------------
80 //! Previous versions of the compiler resorted to feeding NodeIds into the
81 //! symbol hash in order to disambiguate between items with the same path. The
82 //! current version of the name generation algorithm takes great care not to do
83 //! that, since NodeIds are notoriously unstable: A small change to the
84 //! code base will offset all NodeIds after the change and thus, much as using
85 //! the SVH in the hash, invalidate an unbounded number of symbol names. This
86 //! makes re-using previously compiled code for incremental compilation
87 //! virtually impossible. Thus, symbol hash generation exclusively relies on
88 //! DefPaths which are much more robust in the face of changes to the code base.
90 use rustc::hir::def_id::{CrateNum, DefId, LOCAL_CRATE};
92 use rustc::hir::CodegenFnAttrFlags;
93 use rustc::hir::map::{DefPathData, DisambiguatedDefPathData};
94 use rustc::ich::NodeIdHashingMode;
95 use rustc::ty::print::{PrettyPrinter, Printer, Print};
96 use rustc::ty::query::Providers;
97 use rustc::ty::subst::{Kind, SubstsRef, UnpackedKind};
98 use rustc::ty::{self, Ty, TyCtxt, TypeFoldable};
99 use rustc::util::common::record_time;
100 use rustc_data_structures::stable_hasher::{HashStable, StableHasher};
101 use rustc_mir::monomorphize::item::{InstantiationMode, MonoItem, MonoItemExt};
102 use rustc_mir::monomorphize::Instance;
104 use syntax_pos::symbol::Symbol;
108 use std::fmt::{self, Write};
109 use std::mem::{self, discriminant};
111 pub fn provide(providers: &mut Providers<'_>) {
112 *providers = Providers {
120 fn get_symbol_hash<'a, 'tcx>(
121 tcx: TyCtxt<'a, 'tcx, 'tcx>,
123 // the DefId of the item this name is for
126 // instance this name will be for
127 instance: Instance<'tcx>,
129 // type of the item, without any generic
130 // parameters substituted; this is
131 // included in the hash as a kind of
135 // values for generic type parameters,
137 substs: SubstsRef<'tcx>,
140 "get_symbol_hash(def_id={:?}, parameters={:?})",
144 let mut hasher = StableHasher::<u64>::new();
145 let mut hcx = tcx.create_stable_hashing_context();
147 record_time(&tcx.sess.perf_stats.symbol_hash_time, || {
148 // the main symbol name is not necessarily unique; hash in the
149 // compiler's internal def-path, guaranteeing each symbol has a
151 tcx.def_path_hash(def_id).hash_stable(&mut hcx, &mut hasher);
153 // Include the main item-type. Note that, in this case, the
154 // assertions about `needs_subst` may not hold, but this item-type
155 // ought to be the same for every reference anyway.
156 assert!(!item_type.has_erasable_regions());
157 hcx.while_hashing_spans(false, |hcx| {
158 hcx.with_node_id_hashing_mode(NodeIdHashingMode::HashDefPath, |hcx| {
159 item_type.hash_stable(hcx, &mut hasher);
163 // If this is a function, we hash the signature as well.
164 // This is not *strictly* needed, but it may help in some
165 // situations, see the `run-make/a-b-a-linker-guard` test.
166 if let ty::FnDef(..) = item_type.sty {
167 item_type.fn_sig(tcx).hash_stable(&mut hcx, &mut hasher);
170 // also include any type parameters (for generic items)
171 assert!(!substs.has_erasable_regions());
172 assert!(!substs.needs_subst());
173 substs.hash_stable(&mut hcx, &mut hasher);
175 let is_generic = substs.non_erasable_generics().next().is_some();
176 let avoid_cross_crate_conflicts =
177 // If this is an instance of a generic function, we also hash in
178 // the ID of the instantiating crate. This avoids symbol conflicts
179 // in case the same instances is emitted in two crates of the same
183 // If we're dealing with an instance of a function that's inlined from
184 // another crate but we're marking it as globally shared to our
185 // compliation (aka we're not making an internal copy in each of our
186 // codegen units) then this symbol may become an exported (but hidden
187 // visibility) symbol. This means that multiple crates may do the same
188 // and we want to be sure to avoid any symbol conflicts here.
189 match MonoItem::Fn(instance).instantiation_mode(tcx) {
190 InstantiationMode::GloballyShared { may_conflict: true } => true,
194 if avoid_cross_crate_conflicts {
195 let instantiating_crate = if is_generic {
196 if !def_id.is_local() && tcx.sess.opts.share_generics() {
197 // If we are re-using a monomorphization from another crate,
198 // we have to compute the symbol hash accordingly.
199 let upstream_monomorphizations = tcx.upstream_monomorphizations_for(def_id);
201 upstream_monomorphizations
202 .and_then(|monos| monos.get(&substs).cloned())
203 .unwrap_or(LOCAL_CRATE)
211 (&tcx.original_crate_name(instantiating_crate).as_str()[..])
212 .hash_stable(&mut hcx, &mut hasher);
213 (&tcx.crate_disambiguator(instantiating_crate)).hash_stable(&mut hcx, &mut hasher);
216 // We want to avoid accidental collision between different types of instances.
217 // Especially, VtableShim may overlap with its original instance without this.
218 discriminant(&instance.def).hash_stable(&mut hcx, &mut hasher);
221 // 64 bits should be enough to avoid collisions.
225 fn def_symbol_name<'a, 'tcx>(tcx: TyCtxt<'a, 'tcx, 'tcx>, def_id: DefId) -> ty::SymbolName {
228 path: SymbolPath::new(),
229 keep_within_component: false,
230 }.print_def_path(def_id, &[]).unwrap().path.into_interned()
233 fn symbol_name<'a, 'tcx>(tcx: TyCtxt<'a, 'tcx, 'tcx>, instance: Instance<'tcx>) -> ty::SymbolName {
235 name: Symbol::intern(&compute_symbol_name(tcx, instance)).as_interned_str(),
239 fn compute_symbol_name<'a, 'tcx>(tcx: TyCtxt<'a, 'tcx, 'tcx>, instance: Instance<'tcx>) -> String {
240 let def_id = instance.def_id();
241 let substs = instance.substs;
243 debug!("symbol_name(def_id={:?}, substs={:?})", def_id, substs);
245 let hir_id = tcx.hir().as_local_hir_id(def_id);
247 if def_id.is_local() {
248 if tcx.plugin_registrar_fn(LOCAL_CRATE) == Some(def_id) {
249 let disambiguator = tcx.sess.local_crate_disambiguator();
250 return tcx.sess.generate_plugin_registrar_symbol(disambiguator);
252 if tcx.proc_macro_decls_static(LOCAL_CRATE) == Some(def_id) {
253 let disambiguator = tcx.sess.local_crate_disambiguator();
254 return tcx.sess.generate_proc_macro_decls_symbol(disambiguator);
258 // FIXME(eddyb) Precompute a custom symbol name based on attributes.
259 let is_foreign = if let Some(id) = hir_id {
260 match tcx.hir().get_by_hir_id(id) {
261 Node::ForeignItem(_) => true,
265 tcx.is_foreign_item(def_id)
268 let attrs = tcx.codegen_fn_attrs(def_id);
270 if let Some(name) = attrs.link_name {
271 return name.to_string();
273 // Don't mangle foreign items.
274 return tcx.item_name(def_id).to_string();
277 if let Some(name) = &attrs.export_name {
279 return name.to_string();
282 if attrs.flags.contains(CodegenFnAttrFlags::NO_MANGLE) {
284 return tcx.item_name(def_id).to_string();
287 // We want to compute the "type" of this item. Unfortunately, some
288 // kinds of items (e.g., closures) don't have an entry in the
289 // item-type array. So walk back up the find the closest parent
290 // that DOES have an entry.
291 let mut ty_def_id = def_id;
294 let key = tcx.def_key(ty_def_id);
295 match key.disambiguated_data.data {
296 DefPathData::TypeNs(_) | DefPathData::ValueNs(_) => {
297 instance_ty = tcx.type_of(ty_def_id);
301 // if we're making a symbol for something, there ought
302 // to be a value or type-def or something in there
304 ty_def_id.index = key.parent.unwrap_or_else(|| {
306 "finding type for {:?}, encountered def-id {:?} with no \
316 // Erase regions because they may not be deterministic when hashed
317 // and should not matter anyhow.
318 let instance_ty = tcx.erase_regions(&instance_ty);
320 let hash = get_symbol_hash(tcx, def_id, instance, instance_ty, substs);
322 let mut printer = SymbolPrinter {
324 path: SymbolPath::from_interned(tcx.def_symbol_name(def_id)),
325 keep_within_component: false,
328 if instance.is_vtable_shim() {
329 let _ = printer.write_str("{{vtable-shim}}");
332 printer.path.finish(hash)
335 // Follow C++ namespace-mangling style, see
336 // http://en.wikipedia.org/wiki/Name_mangling for more info.
338 // It turns out that on macOS you can actually have arbitrary symbols in
339 // function names (at least when given to LLVM), but this is not possible
340 // when using unix's linker. Perhaps one day when we just use a linker from LLVM
341 // we won't need to do this name mangling. The problem with name mangling is
342 // that it seriously limits the available characters. For example we can't
343 // have things like &T in symbol names when one would theoretically
344 // want them for things like impls of traits on that type.
346 // To be able to work on all platforms and get *some* reasonable output, we
347 // use C++ name-mangling.
356 let mut result = SymbolPath {
357 result: String::with_capacity(64),
358 temp_buf: String::with_capacity(16),
360 result.result.push_str("_ZN"); // _Z == Begin name-sequence, N == nested
364 fn from_interned(symbol: ty::SymbolName) -> Self {
365 let mut result = SymbolPath {
366 result: String::with_capacity(64),
367 temp_buf: String::with_capacity(16),
369 result.result.push_str(&symbol.as_str());
373 fn into_interned(mut self) -> ty::SymbolName {
374 self.finalize_pending_component();
376 name: Symbol::intern(&self.result).as_interned_str(),
380 fn finalize_pending_component(&mut self) {
381 if !self.temp_buf.is_empty() {
382 let _ = write!(self.result, "{}{}", self.temp_buf.len(), self.temp_buf);
383 self.temp_buf.clear();
387 fn finish(mut self, hash: u64) -> String {
388 self.finalize_pending_component();
389 // E = end name-sequence
390 let _ = write!(self.result, "17h{:016x}E", hash);
395 struct SymbolPrinter<'a, 'tcx> {
396 tcx: TyCtxt<'a, 'tcx, 'tcx>,
399 // When `true`, `finalize_pending_component` isn't used.
400 // This is needed when recursing into `path_qualified`,
401 // or `path_generic_args`, as any nested paths are
402 // logically within one component.
403 keep_within_component: bool,
406 // HACK(eddyb) this relies on using the `fmt` interface to get
407 // `PrettyPrinter` aka pretty printing of e.g. types in paths,
408 // symbol names should have their own printing machinery.
410 impl Printer<'tcx, 'tcx> for SymbolPrinter<'_, 'tcx> {
411 type Error = fmt::Error;
416 type DynExistential = Self;
418 fn tcx(&'a self) -> TyCtxt<'a, 'tcx, 'tcx> {
424 _region: ty::Region<'_>,
425 ) -> Result<Self::Region, Self::Error> {
432 ) -> Result<Self::Type, Self::Error> {
434 // Print all nominal types as paths (unlike `pretty_print_type`).
435 ty::FnDef(def_id, substs) |
436 ty::Opaque(def_id, substs) |
437 ty::Projection(ty::ProjectionTy { item_def_id: def_id, substs }) |
438 ty::UnnormalizedProjection(ty::ProjectionTy { item_def_id: def_id, substs }) |
439 ty::Closure(def_id, ty::ClosureSubsts { substs }) |
440 ty::Generator(def_id, ty::GeneratorSubsts { substs }, _) => {
441 self.print_def_path(def_id, substs)
443 _ => self.pretty_print_type(ty),
447 fn print_dyn_existential(
449 predicates: &'tcx ty::List<ty::ExistentialPredicate<'tcx>>,
450 ) -> Result<Self::DynExistential, Self::Error> {
451 let mut first = false;
452 for p in predicates {
457 self = p.print(self)?;
465 ) -> Result<Self::Path, Self::Error> {
466 self.write_str(&self.tcx.original_crate_name(cnum).as_str())?;
472 trait_ref: Option<ty::TraitRef<'tcx>>,
473 ) -> Result<Self::Path, Self::Error> {
474 // Similar to `pretty_path_qualified`, but for the other
475 // types that are printed as paths (see `print_type` above).
480 ty::UnnormalizedProjection(_) |
483 if trait_ref.is_none() =>
485 self.print_type(self_ty)
488 _ => self.pretty_path_qualified(self_ty, trait_ref)
494 print_prefix: impl FnOnce(Self) -> Result<Self::Path, Self::Error>,
495 _disambiguated_data: &DisambiguatedDefPathData,
497 trait_ref: Option<ty::TraitRef<'tcx>>,
498 ) -> Result<Self::Path, Self::Error> {
499 self.pretty_path_append_impl(
501 cx = print_prefix(cx)?;
503 if cx.keep_within_component {
504 // HACK(eddyb) print the path similarly to how `FmtPrinter` prints it.
507 cx.path.finalize_pending_component();
518 print_prefix: impl FnOnce(Self) -> Result<Self::Path, Self::Error>,
519 disambiguated_data: &DisambiguatedDefPathData,
520 ) -> Result<Self::Path, Self::Error> {
521 self = print_prefix(self)?;
523 // Skip `::{{constructor}}` on tuple/unit structs.
524 match disambiguated_data.data {
525 DefPathData::StructCtor => return Ok(self),
529 if self.keep_within_component {
530 // HACK(eddyb) print the path similarly to how `FmtPrinter` prints it.
531 self.write_str("::")?;
533 self.path.finalize_pending_component();
536 self.write_str(&disambiguated_data.data.as_interned_str().as_str())?;
539 fn path_generic_args(
541 print_prefix: impl FnOnce(Self) -> Result<Self::Path, Self::Error>,
543 ) -> Result<Self::Path, Self::Error> {
544 self = print_prefix(self)?;
546 let args = args.iter().cloned().filter(|arg| {
548 UnpackedKind::Lifetime(_) => false,
553 if args.clone().next().is_some() {
554 self.generic_delimiters(|cx| cx.comma_sep(args))
561 impl PrettyPrinter<'tcx, 'tcx> for SymbolPrinter<'_, 'tcx> {
562 fn region_should_not_be_omitted(
564 _region: ty::Region<'_>,
570 mut elems: impl Iterator<Item = T>,
571 ) -> Result<Self, Self::Error>
572 where T: Print<'tcx, 'tcx, Self, Output = Self, Error = Self::Error>
574 if let Some(first) = elems.next() {
575 self = first.print(self)?;
577 self.write_str(",")?;
578 self = elem.print(self)?;
584 fn generic_delimiters(
586 f: impl FnOnce(Self) -> Result<Self, Self::Error>,
587 ) -> Result<Self, Self::Error> {
590 let kept_within_component =
591 mem::replace(&mut self.keep_within_component, true);
593 self.keep_within_component = kept_within_component;
601 impl fmt::Write for SymbolPrinter<'_, '_> {
602 fn write_str(&mut self, s: &str) -> fmt::Result {
603 // Name sanitation. LLVM will happily accept identifiers with weird names, but
605 // gas accepts the following characters in symbols: a-z, A-Z, 0-9, ., _, $
606 // NVPTX assembly has more strict naming rules than gas, so additionally, dots
607 // are replaced with '$' there.
610 if self.path.temp_buf.is_empty() {
612 'a'..='z' | 'A'..='Z' | '_' => {}
614 // Underscore-qualify anything that didn't start as an ident.
615 self.path.temp_buf.push('_');
620 // Escape these with $ sequences
621 '@' => self.path.temp_buf.push_str("$SP$"),
622 '*' => self.path.temp_buf.push_str("$BP$"),
623 '&' => self.path.temp_buf.push_str("$RF$"),
624 '<' => self.path.temp_buf.push_str("$LT$"),
625 '>' => self.path.temp_buf.push_str("$GT$"),
626 '(' => self.path.temp_buf.push_str("$LP$"),
627 ')' => self.path.temp_buf.push_str("$RP$"),
628 ',' => self.path.temp_buf.push_str("$C$"),
630 '-' | ':' | '.' if self.tcx.has_strict_asm_symbol_naming() => {
631 // NVPTX doesn't support these characters in symbol names.
632 self.path.temp_buf.push('$')
635 // '.' doesn't occur in types and functions, so reuse it
637 '-' | ':' => self.path.temp_buf.push('.'),
639 // These are legal symbols
640 'a'..='z' | 'A'..='Z' | '0'..='9' | '_' | '.' | '$' => self.path.temp_buf.push(c),
643 self.path.temp_buf.push('$');
644 for c in c.escape_unicode().skip(1) {
647 '}' => self.path.temp_buf.push('$'),
648 c => self.path.temp_buf.push(c),