src/librustc_hir/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 pub use self::LangItem::*;
  11
  12 use crate::def_id::DefId;
  13 use crate::Target;
  14
  15 use rustc_ast::ast;
  16 use rustc_data_structures::fx::FxHashMap;
  17 use rustc_data_structures::stable_hasher::{HashStable, StableHasher};
  18 use rustc_macros::HashStable_Generic;
  19 use rustc_span::symbol::{sym, Symbol};
  20 use rustc_span::Span;
  21
  22 use lazy_static::lazy_static;
  23
  24 pub enum LangItemGroup {
  25     Op,
  26 }
  27
  28 const NUM_GROUPS: usize = 1;
  29
  30 macro_rules! expand_group {
  31     () => {
  32         None
  33     };
  34     ($group:expr) => {
  35         Some($group)
  36     };
  37 }
  38
  39 // The actual lang items defined come at the end of this file in one handy table.
  40 // So you probably just want to nip down to the end.
  41 macro_rules! language_item_table {
  42     (
  43         $( $variant:ident $($group:expr)?, $name:expr, $method:ident, $target:expr; )*
  44     ) => {
  45
  46         enum_from_u32! {
  47             /// A representation of all the valid language items in Rust.
  48             #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, RustcEncodable, RustcDecodable)]
  49             pub enum LangItem {
  50                 $($variant,)*
  51             }
  52         }
  53
  54         impl LangItem {
  55             /// Returns the `name` in `#[lang = "$name"]`.
  56             /// For example, `LangItem::EqTraitLangItem`,
  57             /// that is `#[lang = "eq"]` would result in `"eq"`.
  58             pub fn name(self) -> &'static str {
  59                 match self {
  60                     $( $variant => $name, )*
  61                 }
  62             }
  63
  64             pub fn group(self) -> Option<LangItemGroup> {
  65                 use LangItemGroup::*;
  66                 match self {
  67                     $( $variant => expand_group!($($group)*), )*
  68                 }
  69             }
  70         }
  71
  72         #[derive(HashStable_Generic)]
  73         pub struct LanguageItems {
  74             /// Mappings from lang items to their possibly found `DefId`s.
  75             /// The index corresponds to the order in `LangItem`.
  76             pub items: Vec<Option<DefId>>,
  77             /// Lang items that were not found during collection.
  78             pub missing: Vec<LangItem>,
  79             /// Mapping from `LangItemGroup` discriminants to all
  80             /// `DefId`s of lang items in that group.
  81             pub groups: [Vec<DefId>; NUM_GROUPS],
  82         }
  83
  84         impl LanguageItems {
  85             /// Construct an empty collection of lang items and no missing ones.
  86             pub fn new() -> Self {
  87                 fn init_none(_: LangItem) -> Option<DefId> { None }
  88
  89                 Self {
  90                     items: vec![$(init_none($variant)),*],
  91                     missing: Vec::new(),
  92                     groups: [vec![]; NUM_GROUPS],
  93                 }
  94             }
  95
  96             /// Returns the mappings to the possibly found `DefId`s for each lang item.
  97             pub fn items(&self) -> &[Option<DefId>] {
  98                 &*self.items
  99             }
 100
 101             /// Requires that a given `LangItem` was bound and returns the corresponding `DefId`.
 102             /// If it wasn't bound, e.g. due to a missing `#[lang = "<it.name()>"]`,
 103             /// returns an error message as a string.
 104             pub fn require(&self, it: LangItem) -> Result<DefId, String> {
 105                 self.items[it as usize].ok_or_else(|| format!("requires `{}` lang_item", it.name()))
 106             }
 107
 108             pub fn group(&self, group: LangItemGroup) -> &[DefId] {
 109                 self.groups[group as usize].as_ref()
 110             }
 111
 112             $(
 113                 /// Returns the corresponding `DefId` for the lang item
 114                 #[doc = $name]
 115                 /// if it exists.
 116                 #[allow(dead_code)]
 117                 pub fn $method(&self) -> Option<DefId> {
 118                     self.items[$variant as usize]
 119                 }
 120             )*
 121         }
 122
 123         lazy_static! {
 124             /// A mapping from the name of the lang item to its order and the form it must be of.
 125             pub static ref ITEM_REFS: FxHashMap<&'static str, (usize, Target)> = {
 126                 let mut item_refs = FxHashMap::default();
 127                 $( item_refs.insert($name, ($variant as usize, $target)); )*
 128                 item_refs
 129             };
 130         }
 131
 132 // End of the macro
 133     }
 134 }
 135
 136 impl<CTX> HashStable<CTX> for LangItem {
 137     fn hash_stable(&self, _: &mut CTX, hasher: &mut StableHasher) {
 138         ::std::hash::Hash::hash(self, hasher);
 139     }
 140 }
 141
 142 /// Extracts the first `lang = "$name"` out of a list of attributes.
 143 /// The attributes `#[panic_handler]` and `#[alloc_error_handler]`
 144 /// are also extracted out when found.
 145 pub fn extract(attrs: &[ast::Attribute]) -> Option<(Symbol, Span)> {
 146     attrs.iter().find_map(|attr| {
 147         Some(match attr {
 148             _ if attr.check_name(sym::lang) => (attr.value_str()?, attr.span),
 149             _ if attr.check_name(sym::panic_handler) => (sym::panic_impl, attr.span),
 150             _ if attr.check_name(sym::alloc_error_handler) => (sym::oom, attr.span),
 151             _ => return None,
 152         })
 153     })
 154 }
 155
 156 language_item_table! {
 157 //  Variant name,                Name,                 Method name,             Target;
 158     BoolImplItem,                "bool",               bool_impl,               Target::Impl;
 159     CharImplItem,                "char",               char_impl,               Target::Impl;
 160     StrImplItem,                 "str",                str_impl,                Target::Impl;
 161     SliceImplItem,               "slice",              slice_impl,              Target::Impl;
 162     SliceU8ImplItem,             "slice_u8",           slice_u8_impl,           Target::Impl;
 163     StrAllocImplItem,            "str_alloc",          str_alloc_impl,          Target::Impl;
 164     SliceAllocImplItem,          "slice_alloc",        slice_alloc_impl,        Target::Impl;
 165     SliceU8AllocImplItem,        "slice_u8_alloc",     slice_u8_alloc_impl,     Target::Impl;
 166     ConstPtrImplItem,            "const_ptr",          const_ptr_impl,          Target::Impl;
 167     MutPtrImplItem,              "mut_ptr",            mut_ptr_impl,            Target::Impl;
 168     ConstSlicePtrImplItem,       "const_slice_ptr",    const_slice_ptr_impl,    Target::Impl;
 169     MutSlicePtrImplItem,         "mut_slice_ptr",      mut_slice_ptr_impl,      Target::Impl;
 170     I8ImplItem,                  "i8",                 i8_impl,                 Target::Impl;
 171     I16ImplItem,                 "i16",                i16_impl,                Target::Impl;
 172     I32ImplItem,                 "i32",                i32_impl,                Target::Impl;
 173     I64ImplItem,                 "i64",                i64_impl,                Target::Impl;
 174     I128ImplItem,                "i128",               i128_impl,               Target::Impl;
 175     IsizeImplItem,               "isize",              isize_impl,              Target::Impl;
 176     U8ImplItem,                  "u8",                 u8_impl,                 Target::Impl;
 177     U16ImplItem,                 "u16",                u16_impl,                Target::Impl;
 178     U32ImplItem,                 "u32",                u32_impl,                Target::Impl;
 179     U64ImplItem,                 "u64",                u64_impl,                Target::Impl;
 180     U128ImplItem,                "u128",               u128_impl,               Target::Impl;
 181     UsizeImplItem,               "usize",              usize_impl,              Target::Impl;
 182     F32ImplItem,                 "f32",                f32_impl,                Target::Impl;
 183     F64ImplItem,                 "f64",                f64_impl,                Target::Impl;
 184     F32RuntimeImplItem,          "f32_runtime",        f32_runtime_impl,        Target::Impl;
 185     F64RuntimeImplItem,          "f64_runtime",        f64_runtime_impl,        Target::Impl;
 186
 187     SizedTraitLangItem,          "sized",              sized_trait,             Target::Trait;
 188     UnsizeTraitLangItem,         "unsize",             unsize_trait,            Target::Trait;
 189     // trait injected by #[derive(PartialEq)], (i.e. "Partial EQ").
 190     StructuralPeqTraitLangItem,  "structural_peq",     structural_peq_trait,    Target::Trait;
 191     // trait injected by #[derive(Eq)], (i.e. "Total EQ"; no, I will not apologize).
 192     StructuralTeqTraitLangItem,  "structural_teq",     structural_teq_trait,    Target::Trait;
 193     CopyTraitLangItem,           "copy",               copy_trait,              Target::Trait;
 194     CloneTraitLangItem,          "clone",              clone_trait,             Target::Trait;
 195     SyncTraitLangItem,           "sync",               sync_trait,              Target::Trait;
 196     DiscriminantKindTraitLangItem,"discriminant_kind", discriminant_kind_trait, Target::Trait;
 197     FreezeTraitLangItem,         "freeze",             freeze_trait,            Target::Trait;
 198
 199     DropTraitLangItem,           "drop",               drop_trait,              Target::Trait;
 200
 201     CoerceUnsizedTraitLangItem,  "coerce_unsized",     coerce_unsized_trait,    Target::Trait;
 202     DispatchFromDynTraitLangItem,"dispatch_from_dyn",  dispatch_from_dyn_trait, Target::Trait;
 203
 204     AddTraitLangItem(Op),        "add",                add_trait,               Target::Trait;
 205     SubTraitLangItem(Op),        "sub",                sub_trait,               Target::Trait;
 206     MulTraitLangItem(Op),        "mul",                mul_trait,               Target::Trait;
 207     DivTraitLangItem(Op),        "div",                div_trait,               Target::Trait;
 208     RemTraitLangItem(Op),        "rem",                rem_trait,               Target::Trait;
 209     NegTraitLangItem(Op),        "neg",                neg_trait,               Target::Trait;
 210     NotTraitLangItem(Op),        "not",                not_trait,               Target::Trait;
 211     BitXorTraitLangItem(Op),     "bitxor",             bitxor_trait,            Target::Trait;
 212     BitAndTraitLangItem(Op),     "bitand",             bitand_trait,            Target::Trait;
 213     BitOrTraitLangItem(Op),      "bitor",              bitor_trait,             Target::Trait;
 214     ShlTraitLangItem(Op),        "shl",                shl_trait,               Target::Trait;
 215     ShrTraitLangItem(Op),        "shr",                shr_trait,               Target::Trait;
 216     AddAssignTraitLangItem(Op),  "add_assign",         add_assign_trait,        Target::Trait;
 217     SubAssignTraitLangItem(Op),  "sub_assign",         sub_assign_trait,        Target::Trait;
 218     MulAssignTraitLangItem(Op),  "mul_assign",         mul_assign_trait,        Target::Trait;
 219     DivAssignTraitLangItem(Op),  "div_assign",         div_assign_trait,        Target::Trait;
 220     RemAssignTraitLangItem(Op),  "rem_assign",         rem_assign_trait,        Target::Trait;
 221     BitXorAssignTraitLangItem(Op),"bitxor_assign",     bitxor_assign_trait,     Target::Trait;
 222     BitAndAssignTraitLangItem(Op),"bitand_assign",     bitand_assign_trait,     Target::Trait;
 223     BitOrAssignTraitLangItem(Op),"bitor_assign",       bitor_assign_trait,      Target::Trait;
 224     ShlAssignTraitLangItem(Op),  "shl_assign",         shl_assign_trait,        Target::Trait;
 225     ShrAssignTraitLangItem(Op),  "shr_assign",         shr_assign_trait,        Target::Trait;
 226     IndexTraitLangItem(Op),      "index",              index_trait,             Target::Trait;
 227     IndexMutTraitLangItem(Op),   "index_mut",          index_mut_trait,         Target::Trait;
 228
 229     UnsafeCellTypeLangItem,      "unsafe_cell",        unsafe_cell_type,        Target::Struct;
 230     VaListTypeLangItem,          "va_list",            va_list,                 Target::Struct;
 231
 232     DerefTraitLangItem,          "deref",              deref_trait,             Target::Trait;
 233     DerefMutTraitLangItem,       "deref_mut",          deref_mut_trait,         Target::Trait;
 234     ReceiverTraitLangItem,       "receiver",           receiver_trait,          Target::Trait;
 235
 236     FnTraitLangItem,             "fn",                 fn_trait,                Target::Trait;
 237     FnMutTraitLangItem,          "fn_mut",             fn_mut_trait,            Target::Trait;
 238     FnOnceTraitLangItem,         "fn_once",            fn_once_trait,           Target::Trait;
 239
 240     FnOnceOutputLangItem,        "fn_once_output",     fn_once_output,          Target::AssocTy;
 241
 242     FutureTraitLangItem,         "future_trait",       future_trait,            Target::Trait;
 243     GeneratorStateLangItem,      "generator_state",    gen_state,               Target::Enum;
 244     GeneratorTraitLangItem,      "generator",          gen_trait,               Target::Trait;
 245     UnpinTraitLangItem,          "unpin",              unpin_trait,             Target::Trait;
 246     PinTypeLangItem,             "pin",                pin_type,                Target::Struct;
 247
 248     // Don't be fooled by the naming here: this lang item denotes `PartialEq`, not `Eq`.
 249     EqTraitLangItem,             "eq",                 eq_trait,                Target::Trait;
 250     PartialOrdTraitLangItem,     "partial_ord",        partial_ord_trait,       Target::Trait;
 251
 252     // A number of panic-related lang items. The `panic` item corresponds to
 253     // divide-by-zero and various panic cases with `match`. The
 254     // `panic_bounds_check` item is for indexing arrays.
 255     //
 256     // The `begin_unwind` lang item has a predefined symbol name and is sort of
 257     // a "weak lang item" in the sense that a crate is not required to have it
 258     // defined to use it, but a final product is required to define it
 259     // somewhere. Additionally, there are restrictions on crates that use a weak
 260     // lang item, but do not have it defined.
 261     PanicFnLangItem,             "panic",              panic_fn,                Target::Fn;
 262     PanicBoundsCheckFnLangItem,  "panic_bounds_check", panic_bounds_check_fn,   Target::Fn;
 263     PanicInfoLangItem,           "panic_info",         panic_info,              Target::Struct;
 264     PanicLocationLangItem,       "panic_location",     panic_location,          Target::Struct;
 265     PanicImplLangItem,           "panic_impl",         panic_impl,              Target::Fn;
 266     // Libstd panic entry point. Necessary for const eval to be able to catch it
 267     BeginPanicFnLangItem,        "begin_panic",        begin_panic_fn,          Target::Fn;
 268
 269     ExchangeMallocFnLangItem,    "exchange_malloc",    exchange_malloc_fn,      Target::Fn;
 270     BoxFreeFnLangItem,           "box_free",           box_free_fn,             Target::Fn;
 271     DropInPlaceFnLangItem,       "drop_in_place",      drop_in_place_fn,        Target::Fn;
 272     OomLangItem,                 "oom",                oom,                     Target::Fn;
 273     AllocLayoutLangItem,         "alloc_layout",       alloc_layout,            Target::Struct;
 274
 275     StartFnLangItem,             "start",              start_fn,                Target::Fn;
 276
 277     CountCodeRegionFnLangItem,   "count_code_region",  count_code_region_fn,    Target::Fn;
 278
 279     EhPersonalityLangItem,       "eh_personality",     eh_personality,          Target::Fn;
 280     EhCatchTypeinfoLangItem,     "eh_catch_typeinfo",  eh_catch_typeinfo,       Target::Static;
 281
 282     OwnedBoxLangItem,            "owned_box",          owned_box,               Target::Struct;
 283
 284     PhantomDataItem,             "phantom_data",       phantom_data,            Target::Struct;
 285
 286     ManuallyDropItem,            "manually_drop",      manually_drop,           Target::Struct;
 287
 288     MaybeUninitLangItem,         "maybe_uninit",       maybe_uninit,            Target::Union;
 289
 290     // Align offset for stride != 1; must not panic.
 291     AlignOffsetLangItem,         "align_offset",       align_offset_fn,         Target::Fn;
 292
 293     TerminationTraitLangItem,    "termination",        termination,             Target::Trait;
 294
 295     TryTraitLangItem,            "try",                try_trait,               Target::Trait;
 296 }