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::{MethodKind, Target};
  12
  13 use rustc_ast as ast;
  14 use rustc_data_structures::fx::FxHashMap;
  15 use rustc_data_structures::stable_hasher::{HashStable, StableHasher};
  16 use rustc_macros::HashStable_Generic;
  17 use rustc_span::symbol::{kw, sym, Symbol};
  18 use rustc_span::Span;
  19
  20 use std::lazy::SyncLazy;
  21
  22 pub enum LangItemGroup {
  23     Op,
  24 }
  25
  26 const NUM_GROUPS: usize = 1;
  27
  28 macro_rules! expand_group {
  29     () => {
  30         None
  31     };
  32     ($group:expr) => {
  33         Some($group)
  34     };
  35 }
  36
  37 // The actual lang items defined come at the end of this file in one handy table.
  38 // So you probably just want to nip down to the end.
  39 macro_rules! language_item_table {
  40     (
  41         $( $variant:ident $($group:expr)?, $name:expr, $method:ident, $target:expr; )*
  42     ) => {
  43
  44         enum_from_u32! {
  45             /// A representation of all the valid language items in Rust.
  46             #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, Encodable, Decodable)]
  47             pub enum LangItem {
  48                 $(
  49                     #[doc = concat!("The `", stringify!($name), "` lang item.")]
  50                     $variant,
  51                 )*
  52             }
  53         }
  54
  55         impl LangItem {
  56             /// Returns the `name` symbol in `#[lang = "$name"]`.
  57             /// For example, [`LangItem::PartialEq`]`.name()`
  58             /// would result in [`sym::eq`] since it is `#[lang = "eq"]`.
  59             pub fn name(self) -> Symbol {
  60                 match self {
  61                     $( LangItem::$variant => $name, )*
  62                 }
  63             }
  64
  65             /// The [group](LangItemGroup) that this lang item belongs to,
  66             /// or `None` if it doesn't belong to a group.
  67             pub fn group(self) -> Option<LangItemGroup> {
  68                 use LangItemGroup::*;
  69                 match self {
  70                     $( LangItem::$variant => expand_group!($($group)*), )*
  71                 }
  72             }
  73         }
  74
  75         /// All of the language items in the current crate, defined or not.
  76         #[derive(HashStable_Generic, Debug)]
  77         pub struct LanguageItems {
  78             /// Mappings from lang items to their possibly found [`DefId`]s.
  79             /// The index corresponds to the order in [`LangItem`].
  80             pub items: Vec<Option<DefId>>,
  81             /// Lang items that were not found during collection.
  82             pub missing: Vec<LangItem>,
  83             /// Mapping from [`LangItemGroup`] discriminants to all
  84             /// [`DefId`]s of lang items in that group.
  85             pub groups: [Vec<DefId>; NUM_GROUPS],
  86         }
  87
  88         impl LanguageItems {
  89             /// Construct an empty collection of lang items and no missing ones.
  90             pub fn new() -> Self {
  91                 fn init_none(_: LangItem) -> Option<DefId> { None }
  92
  93                 Self {
  94                     items: vec![$(init_none(LangItem::$variant)),*],
  95                     missing: Vec::new(),
  96                     groups: [vec![]; NUM_GROUPS],
  97                 }
  98             }
  99
 100             /// Returns the mappings to the possibly found `DefId`s for each lang item.
 101             pub fn items(&self) -> &[Option<DefId>] {
 102                 &*self.items
 103             }
 104
 105             /// Requires that a given `LangItem` was bound and returns the corresponding `DefId`.
 106             /// If it wasn't bound, e.g. due to a missing `#[lang = "<it.name()>"]`,
 107             /// returns an error message as a string.
 108             pub fn require(&self, it: LangItem) -> Result<DefId, String> {
 109                 self.items[it as usize].ok_or_else(|| format!("requires `{}` lang_item", it.name()))
 110             }
 111
 112             /// Returns the [`DefId`]s of all lang items in a group.
 113             pub fn group(&self, group: LangItemGroup) -> &[DefId] {
 114                 self.groups[group as usize].as_ref()
 115             }
 116
 117             $(
 118                 #[doc = concat!("Returns the [`DefId`] of the `", stringify!($name), "` lang item if it is defined.")]
 119                 #[allow(dead_code)]
 120                 pub fn $method(&self) -> Option<DefId> {
 121                     self.items[LangItem::$variant as usize]
 122                 }
 123             )*
 124         }
 125
 126         /// A mapping from the name of the lang item to its order and the form it must be of.
 127         pub static ITEM_REFS: SyncLazy<FxHashMap<Symbol, (usize, Target)>> = SyncLazy::new(|| {
 128             let mut item_refs = FxHashMap::default();
 129             $( item_refs.insert($name, (LangItem::$variant as usize, $target)); )*
 130             item_refs
 131         });
 132
 133 // End of the macro
 134     }
 135 }
 136
 137 impl<CTX> HashStable<CTX> for LangItem {
 138     fn hash_stable(&self, _: &mut CTX, hasher: &mut StableHasher) {
 139         ::std::hash::Hash::hash(self, hasher);
 140     }
 141 }
 142
 143 /// Extracts the first `lang = "$name"` out of a list of attributes.
 144 /// The attributes `#[panic_handler]` and `#[alloc_error_handler]`
 145 /// are also extracted out when found.
 146 ///
 147 /// About the `check_name` argument: passing in a `Session` would be simpler,
 148 /// because then we could call `Session::check_name` directly. But we want to
 149 /// avoid the need for `rustc_hir` to depend on `rustc_session`, so we
 150 /// use a closure instead.
 151 pub fn extract<'a, F>(check_name: F, attrs: &'a [ast::Attribute]) -> Option<(Symbol, Span)>
 152 where
 153     F: Fn(&'a ast::Attribute, Symbol) -> bool,
 154 {
 155     attrs.iter().find_map(|attr| {
 156         Some(match attr {
 157             _ if check_name(attr, sym::lang) => (attr.value_str()?, attr.span),
 158             _ if check_name(attr, sym::panic_handler) => (sym::panic_impl, attr.span),
 159             _ if check_name(attr, sym::alloc_error_handler) => (sym::oom, attr.span),
 160             _ => return None,
 161         })
 162     })
 163 }
 164
 165 language_item_table! {
 166 //  Variant name,            Name,                     Method name,                Target;
 167     Bool,                    sym::bool,                bool_impl,                  Target::Impl;
 168     Char,                    sym::char,                char_impl,                  Target::Impl;
 169     Str,                     sym::str,                 str_impl,                   Target::Impl;
 170     Array,                   sym::array,               array_impl,                 Target::Impl;
 171     Slice,                   sym::slice,               slice_impl,                 Target::Impl;
 172     SliceU8,                 sym::slice_u8,            slice_u8_impl,              Target::Impl;
 173     StrAlloc,                sym::str_alloc,           str_alloc_impl,             Target::Impl;
 174     SliceAlloc,              sym::slice_alloc,         slice_alloc_impl,           Target::Impl;
 175     SliceU8Alloc,            sym::slice_u8_alloc,      slice_u8_alloc_impl,        Target::Impl;
 176     ConstPtr,                sym::const_ptr,           const_ptr_impl,             Target::Impl;
 177     MutPtr,                  sym::mut_ptr,             mut_ptr_impl,               Target::Impl;
 178     ConstSlicePtr,           sym::const_slice_ptr,     const_slice_ptr_impl,       Target::Impl;
 179     MutSlicePtr,             sym::mut_slice_ptr,       mut_slice_ptr_impl,         Target::Impl;
 180     I8,                      sym::i8,                  i8_impl,                    Target::Impl;
 181     I16,                     sym::i16,                 i16_impl,                   Target::Impl;
 182     I32,                     sym::i32,                 i32_impl,                   Target::Impl;
 183     I64,                     sym::i64,                 i64_impl,                   Target::Impl;
 184     I128,                    sym::i128,                i128_impl,                  Target::Impl;
 185     Isize,                   sym::isize,               isize_impl,                 Target::Impl;
 186     U8,                      sym::u8,                  u8_impl,                    Target::Impl;
 187     U16,                     sym::u16,                 u16_impl,                   Target::Impl;
 188     U32,                     sym::u32,                 u32_impl,                   Target::Impl;
 189     U64,                     sym::u64,                 u64_impl,                   Target::Impl;
 190     U128,                    sym::u128,                u128_impl,                  Target::Impl;
 191     Usize,                   sym::usize,               usize_impl,                 Target::Impl;
 192     F32,                     sym::f32,                 f32_impl,                   Target::Impl;
 193     F64,                     sym::f64,                 f64_impl,                   Target::Impl;
 194     F32Runtime,              sym::f32_runtime,         f32_runtime_impl,           Target::Impl;
 195     F64Runtime,              sym::f64_runtime,         f64_runtime_impl,           Target::Impl;
 196
 197     Sized,                   sym::sized,               sized_trait,                Target::Trait;
 198     Unsize,                  sym::unsize,              unsize_trait,               Target::Trait;
 199     // Trait injected by #[derive(PartialEq)], (i.e. "Partial EQ").
 200     StructuralPeq,           sym::structural_peq,      structural_peq_trait,       Target::Trait;
 201     // Trait injected by #[derive(Eq)], (i.e. "Total EQ"; no, I will not apologize).
 202     StructuralTeq,           sym::structural_teq,      structural_teq_trait,       Target::Trait;
 203     Copy,                    sym::copy,                copy_trait,                 Target::Trait;
 204     Clone,                   sym::clone,               clone_trait,                Target::Trait;
 205     Sync,                    sym::sync,                sync_trait,                 Target::Trait;
 206     DiscriminantKind,        sym::discriminant_kind,   discriminant_kind_trait,    Target::Trait;
 207     // The associated item of `trait DiscriminantKind`.
 208     Discriminant,            sym::discriminant_type,   discriminant_type,          Target::AssocTy;
 209
 210     PointeeTrait,            sym::pointee_trait,       pointee_trait,              Target::Trait;
 211     Metadata,                sym::metadata_type,       metadata_type,              Target::AssocTy;
 212     DynMetadata,             sym::dyn_metadata,        dyn_metadata,               Target::Struct;
 213
 214     Freeze,                  sym::freeze,              freeze_trait,               Target::Trait;
 215
 216     Drop,                    sym::drop,                drop_trait,                 Target::Trait;
 217
 218     CoerceUnsized,           sym::coerce_unsized,      coerce_unsized_trait,       Target::Trait;
 219     DispatchFromDyn,         sym::dispatch_from_dyn,   dispatch_from_dyn_trait,    Target::Trait;
 220
 221     Add(Op),                 sym::add,                 add_trait,                  Target::Trait;
 222     Sub(Op),                 sym::sub,                 sub_trait,                  Target::Trait;
 223     Mul(Op),                 sym::mul,                 mul_trait,                  Target::Trait;
 224     Div(Op),                 sym::div,                 div_trait,                  Target::Trait;
 225     Rem(Op),                 sym::rem,                 rem_trait,                  Target::Trait;
 226     Neg(Op),                 sym::neg,                 neg_trait,                  Target::Trait;
 227     Not(Op),                 sym::not,                 not_trait,                  Target::Trait;
 228     BitXor(Op),              sym::bitxor,              bitxor_trait,               Target::Trait;
 229     BitAnd(Op),              sym::bitand,              bitand_trait,               Target::Trait;
 230     BitOr(Op),               sym::bitor,               bitor_trait,                Target::Trait;
 231     Shl(Op),                 sym::shl,                 shl_trait,                  Target::Trait;
 232     Shr(Op),                 sym::shr,                 shr_trait,                  Target::Trait;
 233     AddAssign(Op),           sym::add_assign,          add_assign_trait,           Target::Trait;
 234     SubAssign(Op),           sym::sub_assign,          sub_assign_trait,           Target::Trait;
 235     MulAssign(Op),           sym::mul_assign,          mul_assign_trait,           Target::Trait;
 236     DivAssign(Op),           sym::div_assign,          div_assign_trait,           Target::Trait;
 237     RemAssign(Op),           sym::rem_assign,          rem_assign_trait,           Target::Trait;
 238     BitXorAssign(Op),        sym::bitxor_assign,       bitxor_assign_trait,        Target::Trait;
 239     BitAndAssign(Op),        sym::bitand_assign,       bitand_assign_trait,        Target::Trait;
 240     BitOrAssign(Op),         sym::bitor_assign,        bitor_assign_trait,         Target::Trait;
 241     ShlAssign(Op),           sym::shl_assign,          shl_assign_trait,           Target::Trait;
 242     ShrAssign(Op),           sym::shr_assign,          shr_assign_trait,           Target::Trait;
 243     Index(Op),               sym::index,               index_trait,                Target::Trait;
 244     IndexMut(Op),            sym::index_mut,           index_mut_trait,            Target::Trait;
 245
 246     UnsafeCell,              sym::unsafe_cell,         unsafe_cell_type,           Target::Struct;
 247     VaList,                  sym::va_list,             va_list,                    Target::Struct;
 248
 249     Deref,                   sym::deref,               deref_trait,                Target::Trait;
 250     DerefMut,                sym::deref_mut,           deref_mut_trait,            Target::Trait;
 251     DerefTarget,             sym::deref_target,        deref_target,               Target::AssocTy;
 252     Receiver,                sym::receiver,            receiver_trait,             Target::Trait;
 253
 254     Fn,                      kw::Fn,                   fn_trait,                   Target::Trait;
 255     FnMut,                   sym::fn_mut,              fn_mut_trait,               Target::Trait;
 256     FnOnce,                  sym::fn_once,             fn_once_trait,              Target::Trait;
 257
 258     FnOnceOutput,            sym::fn_once_output,      fn_once_output,             Target::AssocTy;
 259
 260     Future,                  sym::future_trait,        future_trait,               Target::Trait;
 261     GeneratorState,          sym::generator_state,     gen_state,                  Target::Enum;
 262     Generator,               sym::generator,           gen_trait,                  Target::Trait;
 263     Unpin,                   sym::unpin,               unpin_trait,                Target::Trait;
 264     Pin,                     sym::pin,                 pin_type,                   Target::Struct;
 265
 266     PartialEq,               sym::eq,                  eq_trait,                   Target::Trait;
 267     PartialOrd,              sym::partial_ord,         partial_ord_trait,          Target::Trait;
 268
 269     // A number of panic-related lang items. The `panic` item corresponds to divide-by-zero and
 270     // various panic cases with `match`. The `panic_bounds_check` item is for indexing arrays.
 271     //
 272     // The `begin_unwind` lang item has a predefined symbol name and is sort of a "weak lang item"
 273     // in the sense that a crate is not required to have it defined to use it, but a final product
 274     // is required to define it somewhere. Additionally, there are restrictions on crates that use
 275     // a weak lang item, but do not have it defined.
 276     Panic,                   sym::panic,               panic_fn,                   Target::Fn;
 277     PanicStr,                sym::panic_str,           panic_str,                  Target::Fn;
 278     PanicBoundsCheck,        sym::panic_bounds_check,  panic_bounds_check_fn,      Target::Fn;
 279     PanicInfo,               sym::panic_info,          panic_info,                 Target::Struct;
 280     PanicLocation,           sym::panic_location,      panic_location,             Target::Struct;
 281     PanicImpl,               sym::panic_impl,          panic_impl,                 Target::Fn;
 282     // libstd panic entry point. Necessary for const eval to be able to catch it
 283     BeginPanic,              sym::begin_panic,         begin_panic_fn,             Target::Fn;
 284
 285     ExchangeMalloc,          sym::exchange_malloc,     exchange_malloc_fn,         Target::Fn;
 286     BoxFree,                 sym::box_free,            box_free_fn,                Target::Fn;
 287     DropInPlace,             sym::drop_in_place,       drop_in_place_fn,           Target::Fn;
 288     Oom,                     sym::oom,                 oom,                        Target::Fn;
 289     AllocLayout,             sym::alloc_layout,        alloc_layout,               Target::Struct;
 290
 291     Start,                   sym::start,               start_fn,                   Target::Fn;
 292
 293     EhPersonality,           sym::eh_personality,      eh_personality,             Target::Fn;
 294     EhCatchTypeinfo,         sym::eh_catch_typeinfo,   eh_catch_typeinfo,          Target::Static;
 295
 296     OwnedBox,                sym::owned_box,           owned_box,                  Target::Struct;
 297
 298     PhantomData,             sym::phantom_data,        phantom_data,               Target::Struct;
 299
 300     ManuallyDrop,            sym::manually_drop,       manually_drop,              Target::Struct;
 301
 302     MaybeUninit,             sym::maybe_uninit,        maybe_uninit,               Target::Union;
 303
 304     // Align offset for stride != 1; must not panic.
 305     AlignOffset,             sym::align_offset,        align_offset_fn,            Target::Fn;
 306
 307     Termination,             sym::termination,         termination,                Target::Trait;
 308
 309     Try,                     kw::Try,                  try_trait,                  Target::Trait;
 310
 311     // Language items from AST lowering
 312     TryFromError,            sym::from_error,          from_error_fn,              Target::Method(MethodKind::Trait { body: false });
 313     TryFromOk,               sym::from_ok,             from_ok_fn,                 Target::Method(MethodKind::Trait { body: false });
 314     TryIntoResult,           sym::into_result,         into_result_fn,             Target::Method(MethodKind::Trait { body: false });
 315
 316     PollReady,               sym::Ready,               poll_ready_variant,         Target::Variant;
 317     PollPending,             sym::Pending,             poll_pending_variant,       Target::Variant;
 318
 319     FromGenerator,           sym::from_generator,      from_generator_fn,          Target::Fn;
 320     GetContext,              sym::get_context,         get_context_fn,             Target::Fn;
 321
 322     FuturePoll,              sym::poll,                future_poll_fn,             Target::Method(MethodKind::Trait { body: false });
 323
 324     FromFrom,                sym::from,                from_fn,                    Target::Method(MethodKind::Trait { body: false });
 325
 326     OptionSome,              sym::Some,                option_some_variant,        Target::Variant;
 327     OptionNone,              sym::None,                option_none_variant,        Target::Variant;
 328
 329     ResultOk,                sym::Ok,                  result_ok_variant,          Target::Variant;
 330     ResultErr,               sym::Err,                 result_err_variant,         Target::Variant;
 331
 332     IntoIterIntoIter,        sym::into_iter,           into_iter_fn,               Target::Method(MethodKind::Trait { body: false });
 333     IteratorNext,            sym::next,                next_fn,                    Target::Method(MethodKind::Trait { body: false});
 334
 335     PinNewUnchecked,         sym::new_unchecked,       new_unchecked_fn,           Target::Method(MethodKind::Inherent);
 336
 337     RangeFrom,               sym::RangeFrom,           range_from_struct,          Target::Struct;
 338     RangeFull,               sym::RangeFull,           range_full_struct,          Target::Struct;
 339     RangeInclusiveStruct,    sym::RangeInclusive,      range_inclusive_struct,     Target::Struct;
 340     RangeInclusiveNew,       sym::range_inclusive_new, range_inclusive_new_method, Target::Method(MethodKind::Inherent);
 341     Range,                   sym::Range,               range_struct,               Target::Struct;
 342     RangeToInclusive,        sym::RangeToInclusive,    range_to_inclusive_struct,  Target::Struct;
 343     RangeTo,                 sym::RangeTo,             range_to_struct,            Target::Struct;
 344 }