compiler/rustc_hir/src/lang_items.rs

   1 //! Defines language items.
   2 //!
   3 //! Language items are items that represent concepts intrinsic to the language
   4 //! itself. Examples are:
   5 //!
   6 //! * Traits that specify "kinds"; e.g., `Sync`, `Send`.
   7 //! * Traits that represent operators; e.g., `Add`, `Sub`, `Index`.
   8 //! * Functions called by the compiler itself.
   9
  10 use crate::def_id::DefId;
  11 use crate::errors::LangItemError;
  12 use crate::{MethodKind, Target};
  13
  14 use rustc_ast as ast;
  15 use rustc_data_structures::fx::FxIndexMap;
  16 use rustc_data_structures::stable_hasher::{HashStable, StableHasher};
  17 use rustc_macros::HashStable_Generic;
  18 use rustc_span::symbol::{kw, sym, Symbol};
  19 use rustc_span::Span;
  20
  21 use std::sync::LazyLock;
  22
  23 pub enum LangItemGroup {
  24     Op,
  25     Fn,
  26 }
  27
  28 const NUM_GROUPS: usize = 2;
  29
  30 macro_rules! expand_group {
  31     () => {
  32         None
  33     };
  34     ($group:expr) => {
  35         Some($group)
  36     };
  37 }
  38
  39 /// All of the language items, defined or not.
  40 /// Defined lang items can come from the current crate or its dependencies.
  41 #[derive(HashStable_Generic, Debug)]
  42 pub struct LanguageItems {
  43     /// Mappings from lang items to their possibly found [`DefId`]s.
  44     /// The index corresponds to the order in [`LangItem`].
  45     pub items: Vec<Option<DefId>>,
  46     /// Lang items that were not found during collection.
  47     pub missing: Vec<LangItem>,
  48     /// Mapping from [`LangItemGroup`] discriminants to all
  49     /// [`DefId`]s of lang items in that group.
  50     pub groups: [Vec<DefId>; NUM_GROUPS],
  51 }
  52
  53 impl LanguageItems {
  54     pub fn get(&self, item: LangItem) -> Option<DefId> {
  55         self.items[item as usize]
  56     }
  57
  58     pub fn set(&mut self, item: LangItem, def_id: DefId) {
  59         self.items[item as usize] = Some(def_id);
  60     }
  61
  62     /// Requires that a given `LangItem` was bound and returns the corresponding `DefId`.
  63     /// If it wasn't bound, e.g. due to a missing `#[lang = "<it.name()>"]`,
  64     /// returns an error encapsulating the `LangItem`.
  65     pub fn require(&self, it: LangItem) -> Result<DefId, LangItemError> {
  66         self.get(it).ok_or_else(|| LangItemError(it))
  67     }
  68
  69     pub fn iter<'a>(&'a self) -> impl Iterator<Item = (LangItem, DefId)> + 'a {
  70         self.items
  71             .iter()
  72             .enumerate()
  73             .filter_map(|(i, id)| id.map(|id| (LangItem::from_u32(i as u32).unwrap(), id)))
  74     }
  75 }
  76
  77 // The actual lang items defined come at the end of this file in one handy table.
  78 // So you probably just want to nip down to the end.
  79 macro_rules! language_item_table {
  80     (
  81         $( $(#[$attr:meta])* $variant:ident $($group:expr)?, $module:ident :: $name:ident, $method:ident, $target:expr, $generics:expr; )*
  82     ) => {
  83
  84         enum_from_u32! {
  85             /// A representation of all the valid language items in Rust.
  86             #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, Encodable, Decodable)]
  87             pub enum LangItem {
  88                 $(
  89                     #[doc = concat!("The `", stringify!($name), "` lang item.")]
  90                     ///
  91                     $(#[$attr])*
  92                     $variant,
  93                 )*
  94             }
  95         }
  96
  97         impl LangItem {
  98             /// Returns the `name` symbol in `#[lang = "$name"]`.
  99             /// For example, [`LangItem::PartialEq`]`.name()`
 100             /// would result in [`sym::eq`] since it is `#[lang = "eq"]`.
 101             pub fn name(self) -> Symbol {
 102                 match self {
 103                     $( LangItem::$variant => $module::$name, )*
 104                 }
 105             }
 106
 107             /// The [group](LangItemGroup) that this lang item belongs to,
 108             /// or `None` if it doesn't belong to a group.
 109             pub fn group(self) -> Option<LangItemGroup> {
 110                 use LangItemGroup::*;
 111                 match self {
 112                     $( LangItem::$variant => expand_group!($($group)*), )*
 113                 }
 114             }
 115
 116             pub fn required_generics(&self) -> GenericRequirement {
 117                 match self {
 118                     $( LangItem::$variant => $generics, )*
 119                 }
 120             }
 121         }
 122
 123         impl LanguageItems {
 124             /// Construct an empty collection of lang items and no missing ones.
 125             pub fn new() -> Self {
 126                 fn init_none(_: LangItem) -> Option<DefId> { None }
 127                 const EMPTY: Vec<DefId> = Vec::new();
 128
 129                 Self {
 130                     items: vec![$(init_none(LangItem::$variant)),*],
 131                     missing: Vec::new(),
 132                     groups: [EMPTY; NUM_GROUPS],
 133                 }
 134             }
 135
 136             /// Returns the mappings to the possibly found `DefId`s for each lang item.
 137             pub fn items(&self) -> &[Option<DefId>] {
 138                 &*self.items
 139             }
 140
 141             /// Returns the [`DefId`]s of all lang items in a group.
 142             pub fn group(&self, group: LangItemGroup) -> &[DefId] {
 143                 self.groups[group as usize].as_ref()
 144             }
 145
 146             $(
 147                 #[doc = concat!("Returns the [`DefId`] of the `", stringify!($name), "` lang item if it is defined.")]
 148                 pub fn $method(&self) -> Option<DefId> {
 149                     self.items[LangItem::$variant as usize]
 150                 }
 151             )*
 152         }
 153
 154         /// A mapping from the name of the lang item to its order and the form it must be of.
 155         pub static ITEM_REFS: LazyLock<FxIndexMap<Symbol, (usize, Target)>> = LazyLock::new(|| {
 156             let mut item_refs = FxIndexMap::default();
 157             $( item_refs.insert($module::$name, (LangItem::$variant as usize, $target)); )*
 158             item_refs
 159         });
 160
 161 // End of the macro
 162     }
 163 }
 164
 165 impl<CTX> HashStable<CTX> for LangItem {
 166     fn hash_stable(&self, _: &mut CTX, hasher: &mut StableHasher) {
 167         ::std::hash::Hash::hash(self, hasher);
 168     }
 169 }
 170
 171 /// Extracts the first `lang = "$name"` out of a list of attributes.
 172 /// The attributes `#[panic_handler]` and `#[alloc_error_handler]`
 173 /// are also extracted out when found.
 174 pub fn extract(attrs: &[ast::Attribute]) -> Option<(Symbol, Span)> {
 175     attrs.iter().find_map(|attr| {
 176         Some(match attr {
 177             _ if attr.has_name(sym::lang) => (attr.value_str()?, attr.span),
 178             _ if attr.has_name(sym::panic_handler) => (sym::panic_impl, attr.span),
 179             _ if attr.has_name(sym::alloc_error_handler) => (sym::oom, attr.span),
 180             _ => return None,
 181         })
 182     })
 183 }
 184
 185 language_item_table! {
 186 //  Variant name,            Name,                     Method name,                Target                  Generic requirements;
 187     Sized,                   sym::sized,               sized_trait,                Target::Trait,          GenericRequirement::Exact(0);
 188     Unsize,                  sym::unsize,              unsize_trait,               Target::Trait,          GenericRequirement::Minimum(1);
 189     /// Trait injected by `#[derive(PartialEq)]`, (i.e. "Partial EQ").
 190     StructuralPeq,           sym::structural_peq,      structural_peq_trait,       Target::Trait,          GenericRequirement::None;
 191     /// Trait injected by `#[derive(Eq)]`, (i.e. "Total EQ"; no, I will not apologize).
 192     StructuralTeq,           sym::structural_teq,      structural_teq_trait,       Target::Trait,          GenericRequirement::None;
 193     Copy,                    sym::copy,                copy_trait,                 Target::Trait,          GenericRequirement::Exact(0);
 194     Clone,                   sym::clone,               clone_trait,                Target::Trait,          GenericRequirement::None;
 195     Sync,                    sym::sync,                sync_trait,                 Target::Trait,          GenericRequirement::Exact(0);
 196     DiscriminantKind,        sym::discriminant_kind,   discriminant_kind_trait,    Target::Trait,          GenericRequirement::None;
 197     /// The associated item of the [`DiscriminantKind`] trait.
 198     Discriminant,            sym::discriminant_type,   discriminant_type,          Target::AssocTy,        GenericRequirement::None;
 199
 200     PointeeTrait,            sym::pointee_trait,       pointee_trait,              Target::Trait,          GenericRequirement::None;
 201     Metadata,                sym::metadata_type,       metadata_type,              Target::AssocTy,        GenericRequirement::None;
 202     DynMetadata,             sym::dyn_metadata,        dyn_metadata,               Target::Struct,         GenericRequirement::None;
 203
 204     Freeze,                  sym::freeze,              freeze_trait,               Target::Trait,          GenericRequirement::Exact(0);
 205
 206     Drop,                    sym::drop,                drop_trait,                 Target::Trait,          GenericRequirement::None;
 207     Destruct,                sym::destruct,            destruct_trait,             Target::Trait,          GenericRequirement::None;
 208
 209     CoerceUnsized,           sym::coerce_unsized,      coerce_unsized_trait,       Target::Trait,          GenericRequirement::Minimum(1);
 210     DispatchFromDyn,         sym::dispatch_from_dyn,   dispatch_from_dyn_trait,    Target::Trait,          GenericRequirement::Minimum(1);
 211
 212     // language items relating to transmutability
 213     TransmuteOpts,           sym::transmute_opts,      transmute_opts,             Target::Struct,         GenericRequirement::Exact(0);
 214     TransmuteTrait,          sym::transmute_trait,     transmute_trait,            Target::Trait,          GenericRequirement::Exact(3);
 215
 216     Add(Op),                 sym::add,                 add_trait,                  Target::Trait,          GenericRequirement::Exact(1);
 217     Sub(Op),                 sym::sub,                 sub_trait,                  Target::Trait,          GenericRequirement::Exact(1);
 218     Mul(Op),                 sym::mul,                 mul_trait,                  Target::Trait,          GenericRequirement::Exact(1);
 219     Div(Op),                 sym::div,                 div_trait,                  Target::Trait,          GenericRequirement::Exact(1);
 220     Rem(Op),                 sym::rem,                 rem_trait,                  Target::Trait,          GenericRequirement::Exact(1);
 221     Neg(Op),                 sym::neg,                 neg_trait,                  Target::Trait,          GenericRequirement::Exact(0);
 222     Not(Op),                 sym::not,                 not_trait,                  Target::Trait,          GenericRequirement::Exact(0);
 223     BitXor(Op),              sym::bitxor,              bitxor_trait,               Target::Trait,          GenericRequirement::Exact(1);
 224     BitAnd(Op),              sym::bitand,              bitand_trait,               Target::Trait,          GenericRequirement::Exact(1);
 225     BitOr(Op),               sym::bitor,               bitor_trait,                Target::Trait,          GenericRequirement::Exact(1);
 226     Shl(Op),                 sym::shl,                 shl_trait,                  Target::Trait,          GenericRequirement::Exact(1);
 227     Shr(Op),                 sym::shr,                 shr_trait,                  Target::Trait,          GenericRequirement::Exact(1);
 228     AddAssign(Op),           sym::add_assign,          add_assign_trait,           Target::Trait,          GenericRequirement::Exact(1);
 229     SubAssign(Op),           sym::sub_assign,          sub_assign_trait,           Target::Trait,          GenericRequirement::Exact(1);
 230     MulAssign(Op),           sym::mul_assign,          mul_assign_trait,           Target::Trait,          GenericRequirement::Exact(1);
 231     DivAssign(Op),           sym::div_assign,          div_assign_trait,           Target::Trait,          GenericRequirement::Exact(1);
 232     RemAssign(Op),           sym::rem_assign,          rem_assign_trait,           Target::Trait,          GenericRequirement::Exact(1);
 233     BitXorAssign(Op),        sym::bitxor_assign,       bitxor_assign_trait,        Target::Trait,          GenericRequirement::Exact(1);
 234     BitAndAssign(Op),        sym::bitand_assign,       bitand_assign_trait,        Target::Trait,          GenericRequirement::Exact(1);
 235     BitOrAssign(Op),         sym::bitor_assign,        bitor_assign_trait,         Target::Trait,          GenericRequirement::Exact(1);
 236     ShlAssign(Op),           sym::shl_assign,          shl_assign_trait,           Target::Trait,          GenericRequirement::Exact(1);
 237     ShrAssign(Op),           sym::shr_assign,          shr_assign_trait,           Target::Trait,          GenericRequirement::Exact(1);
 238     Index(Op),               sym::index,               index_trait,                Target::Trait,          GenericRequirement::Exact(1);
 239     IndexMut(Op),            sym::index_mut,           index_mut_trait,            Target::Trait,          GenericRequirement::Exact(1);
 240
 241     UnsafeCell,              sym::unsafe_cell,         unsafe_cell_type,           Target::Struct,         GenericRequirement::None;
 242     VaList,                  sym::va_list,             va_list,                    Target::Struct,         GenericRequirement::None;
 243
 244     Deref,                   sym::deref,               deref_trait,                Target::Trait,          GenericRequirement::Exact(0);
 245     DerefMut,                sym::deref_mut,           deref_mut_trait,            Target::Trait,          GenericRequirement::Exact(0);
 246     DerefTarget,             sym::deref_target,        deref_target,               Target::AssocTy,        GenericRequirement::None;
 247     Receiver,                sym::receiver,            receiver_trait,             Target::Trait,          GenericRequirement::None;
 248
 249     Fn(Fn),                  kw::Fn,                   fn_trait,                   Target::Trait,          GenericRequirement::Exact(1);
 250     FnMut(Fn),               sym::fn_mut,              fn_mut_trait,               Target::Trait,          GenericRequirement::Exact(1);
 251     FnOnce(Fn),              sym::fn_once,             fn_once_trait,              Target::Trait,          GenericRequirement::Exact(1);
 252
 253     FnOnceOutput,            sym::fn_once_output,      fn_once_output,             Target::AssocTy,        GenericRequirement::None;
 254
 255     Future,                  sym::future_trait,        future_trait,               Target::Trait,          GenericRequirement::Exact(0);
 256     GeneratorState,          sym::generator_state,     gen_state,                  Target::Enum,           GenericRequirement::None;
 257     Generator,               sym::generator,           gen_trait,                  Target::Trait,          GenericRequirement::Minimum(1);
 258     Unpin,                   sym::unpin,               unpin_trait,                Target::Trait,          GenericRequirement::None;
 259     Pin,                     sym::pin,                 pin_type,                   Target::Struct,         GenericRequirement::None;
 260
 261     PartialEq(Op),           sym::eq,                  eq_trait,                   Target::Trait,          GenericRequirement::Exact(1);
 262     PartialOrd(Op),          sym::partial_ord,         partial_ord_trait,          Target::Trait,          GenericRequirement::Exact(1);
 263
 264     // A number of panic-related lang items. The `panic` item corresponds to divide-by-zero and
 265     // various panic cases with `match`. The `panic_bounds_check` item is for indexing arrays.
 266     //
 267     // The `begin_unwind` lang item has a predefined symbol name and is sort of a "weak lang item"
 268     // in the sense that a crate is not required to have it defined to use it, but a final product
 269     // is required to define it somewhere. Additionally, there are restrictions on crates that use
 270     // a weak lang item, but do not have it defined.
 271     Panic,                   sym::panic,               panic_fn,                   Target::Fn,             GenericRequirement::Exact(0);
 272     PanicFmt,                sym::panic_fmt,           panic_fmt,                  Target::Fn,             GenericRequirement::None;
 273     PanicDisplay,            sym::panic_display,       panic_display,              Target::Fn,             GenericRequirement::None;
 274     ConstPanicFmt,           sym::const_panic_fmt,     const_panic_fmt,            Target::Fn,             GenericRequirement::None;
 275     PanicBoundsCheck,        sym::panic_bounds_check,  panic_bounds_check_fn,      Target::Fn,             GenericRequirement::Exact(0);
 276     PanicInfo,               sym::panic_info,          panic_info,                 Target::Struct,         GenericRequirement::None;
 277     PanicLocation,           sym::panic_location,      panic_location,             Target::Struct,         GenericRequirement::None;
 278     PanicImpl,               sym::panic_impl,          panic_impl,                 Target::Fn,             GenericRequirement::None;
 279     PanicNoUnwind,           sym::panic_no_unwind,     panic_no_unwind,            Target::Fn,             GenericRequirement::Exact(0);
 280     /// libstd panic entry point. Necessary for const eval to be able to catch it
 281     BeginPanic,              sym::begin_panic,         begin_panic_fn,             Target::Fn,             GenericRequirement::None;
 282
 283     ExchangeMalloc,          sym::exchange_malloc,     exchange_malloc_fn,         Target::Fn,             GenericRequirement::None;
 284     BoxFree,                 sym::box_free,            box_free_fn,                Target::Fn,             GenericRequirement::Minimum(1);
 285     DropInPlace,             sym::drop_in_place,       drop_in_place_fn,           Target::Fn,             GenericRequirement::Minimum(1);
 286     Oom,                     sym::oom,                 oom,                        Target::Fn,             GenericRequirement::None;
 287     AllocLayout,             sym::alloc_layout,        alloc_layout,               Target::Struct,         GenericRequirement::None;
 288
 289     Start,                   sym::start,               start_fn,                   Target::Fn,             GenericRequirement::Exact(1);
 290
 291     EhPersonality,           sym::eh_personality,      eh_personality,             Target::Fn,             GenericRequirement::None;
 292     EhCatchTypeinfo,         sym::eh_catch_typeinfo,   eh_catch_typeinfo,          Target::Static,         GenericRequirement::None;
 293
 294     OwnedBox,                sym::owned_box,           owned_box,                  Target::Struct,         GenericRequirement::Minimum(1);
 295
 296     PhantomData,             sym::phantom_data,        phantom_data,               Target::Struct,         GenericRequirement::Exact(1);
 297
 298     ManuallyDrop,            sym::manually_drop,       manually_drop,              Target::Struct,         GenericRequirement::None;
 299
 300     MaybeUninit,             sym::maybe_uninit,        maybe_uninit,               Target::Union,          GenericRequirement::None;
 301
 302     /// Align offset for stride != 1; must not panic.
 303     AlignOffset,             sym::align_offset,        align_offset_fn,            Target::Fn,             GenericRequirement::None;
 304
 305     Termination,             sym::termination,         termination,                Target::Trait,          GenericRequirement::None;
 306
 307     Try,                     sym::Try,                 try_trait,                  Target::Trait,          GenericRequirement::None;
 308
 309     Tuple,                   sym::tuple_trait,         tuple_trait,                Target::Trait,          GenericRequirement::Exact(0);
 310
 311     SliceLen,                sym::slice_len_fn,        slice_len_fn,               Target::Method(MethodKind::Inherent), GenericRequirement::None;
 312
 313     // Language items from AST lowering
 314     TryTraitFromResidual,    sym::from_residual,       from_residual_fn,           Target::Method(MethodKind::Trait { body: false }), GenericRequirement::None;
 315     TryTraitFromOutput,      sym::from_output,         from_output_fn,             Target::Method(MethodKind::Trait { body: false }), GenericRequirement::None;
 316     TryTraitBranch,          sym::branch,              branch_fn,                  Target::Method(MethodKind::Trait { body: false }), GenericRequirement::None;
 317     TryTraitFromYeet,        sym::from_yeet,           from_yeet_fn,               Target::Fn,             GenericRequirement::None;
 318
 319     PollReady,               sym::Ready,               poll_ready_variant,         Target::Variant,        GenericRequirement::None;
 320     PollPending,             sym::Pending,             poll_pending_variant,       Target::Variant,        GenericRequirement::None;
 321
 322     FromGenerator,           sym::from_generator,      from_generator_fn,          Target::Fn,             GenericRequirement::None;
 323     GetContext,              sym::get_context,         get_context_fn,             Target::Fn,             GenericRequirement::None;
 324
 325     FuturePoll,              sym::poll,                future_poll_fn,             Target::Method(MethodKind::Trait { body: false }), GenericRequirement::None;
 326
 327     FromFrom,                sym::from,                from_fn,                    Target::Method(MethodKind::Trait { body: false }), GenericRequirement::None;
 328
 329     OptionSome,              sym::Some,                option_some_variant,        Target::Variant,        GenericRequirement::None;
 330     OptionNone,              sym::None,                option_none_variant,        Target::Variant,        GenericRequirement::None;
 331
 332     ResultOk,                sym::Ok,                  result_ok_variant,          Target::Variant,        GenericRequirement::None;
 333     ResultErr,               sym::Err,                 result_err_variant,         Target::Variant,        GenericRequirement::None;
 334
 335     ControlFlowContinue,     sym::Continue,            cf_continue_variant,        Target::Variant,        GenericRequirement::None;
 336     ControlFlowBreak,        sym::Break,               cf_break_variant,           Target::Variant,        GenericRequirement::None;
 337
 338     IntoFutureIntoFuture,    sym::into_future,         into_future_fn,             Target::Method(MethodKind::Trait { body: false }), GenericRequirement::None;
 339     IntoIterIntoIter,        sym::into_iter,           into_iter_fn,               Target::Method(MethodKind::Trait { body: false }), GenericRequirement::None;
 340     IteratorNext,            sym::next,                next_fn,                    Target::Method(MethodKind::Trait { body: false}), GenericRequirement::None;
 341
 342     PinNewUnchecked,         sym::new_unchecked,       new_unchecked_fn,           Target::Method(MethodKind::Inherent), GenericRequirement::None;
 343
 344     RangeFrom,               sym::RangeFrom,           range_from_struct,          Target::Struct,         GenericRequirement::None;
 345     RangeFull,               sym::RangeFull,           range_full_struct,          Target::Struct,         GenericRequirement::None;
 346     RangeInclusiveStruct,    sym::RangeInclusive,      range_inclusive_struct,     Target::Struct,         GenericRequirement::None;
 347     RangeInclusiveNew,       sym::range_inclusive_new, range_inclusive_new_method, Target::Method(MethodKind::Inherent), GenericRequirement::None;
 348     Range,                   sym::Range,               range_struct,               Target::Struct,         GenericRequirement::None;
 349     RangeToInclusive,        sym::RangeToInclusive,    range_to_inclusive_struct,  Target::Struct,         GenericRequirement::None;
 350     RangeTo,                 sym::RangeTo,             range_to_struct,            Target::Struct,         GenericRequirement::None;
 351 }
 352
 353 pub enum GenericRequirement {
 354     None,
 355     Minimum(usize),
 356     Exact(usize),
 357 }