1 // SPDX-License-Identifier: Apache-2.0 OR MIT 2 3 //! Items which do not have a correspondence to any API in the proc_macro crate, 4 //! but are necessary to include in proc-macro2. 5 6 use crate::fallback; 7 use crate::imp; 8 use crate::marker::{ProcMacroAutoTraits, MARKER}; 9 use crate::Span; 10 use core::fmt::{self, Debug}; 11 12 /// Invalidate any `proc_macro2::Span` that exist on the current thread. 13 /// 14 /// The implementation of `Span` uses thread-local data structures and this 15 /// function clears them. Calling any method on a `Span` on the current thread 16 /// created prior to the invalidation will return incorrect values or crash. 17 /// 18 /// This function is useful for programs that process more than 2<sup>32</sup> 19 /// bytes of Rust source code on the same thread. Just like rustc, proc-macro2 20 /// uses 32-bit source locations, and these wrap around when the total source 21 /// code processed by the same thread exceeds 2<sup>32</sup> bytes (4 22 /// gigabytes). After a wraparound, `Span` methods such as `source_text()` can 23 /// return wrong data. 24 /// 25 /// # Example 26 /// 27 /// As of late 2023, there is 200 GB of Rust code published on crates.io. 28 /// Looking at just the newest version of every crate, it is 16 GB of code. So a 29 /// workload that involves parsing it all would overflow a 32-bit source 30 /// location unless spans are being invalidated. 31 /// 32 /// ``` 33 /// use flate2::read::GzDecoder; 34 /// use std::ffi::OsStr; 35 /// use std::io::{BufReader, Read}; 36 /// use std::str::FromStr; 37 /// use tar::Archive; 38 /// 39 /// rayon::scope(|s| { 40 /// for krate in every_version_of_every_crate() { 41 /// s.spawn(move |_| { 42 /// proc_macro2::extra::invalidate_current_thread_spans(); 43 /// 44 /// let reader = BufReader::new(krate); 45 /// let tar = GzDecoder::new(reader); 46 /// let mut archive = Archive::new(tar); 47 /// for entry in archive.entries().unwrap() { 48 /// let mut entry = entry.unwrap(); 49 /// let path = entry.path().unwrap(); 50 /// if path.extension() != Some(OsStr::new("rs")) { 51 /// continue; 52 /// } 53 /// let mut content = String::new(); 54 /// entry.read_to_string(&mut content).unwrap(); 55 /// match proc_macro2::TokenStream::from_str(&content) { 56 /// Ok(tokens) => {/* ... */}, 57 /// Err(_) => continue, 58 /// } 59 /// } 60 /// }); 61 /// } 62 /// }); 63 /// # 64 /// # fn every_version_of_every_crate() -> Vec<std::fs::File> { 65 /// # Vec::new() 66 /// # } 67 /// ``` 68 /// 69 /// # Panics 70 /// 71 /// This function is not applicable to and will panic if called from a 72 /// procedural macro. 73 #[cfg(span_locations)] 74 #[cfg_attr(docsrs, doc(cfg(feature = "span-locations")))] 75 pub fn invalidate_current_thread_spans() { 76 crate::imp::invalidate_current_thread_spans(); 77 } 78 79 /// An object that holds a [`Group`]'s `span_open()` and `span_close()` together 80 /// in a more compact representation than holding those 2 spans individually. 81 /// 82 /// [`Group`]: crate::Group 83 #[derive(Copy, Clone)] 84 pub struct DelimSpan { 85 inner: DelimSpanEnum, 86 _marker: ProcMacroAutoTraits, 87 } 88 89 #[derive(Copy, Clone)] 90 enum DelimSpanEnum { 91 #[cfg(wrap_proc_macro)] 92 Compiler { 93 join: proc_macro::Span, 94 open: proc_macro::Span, 95 close: proc_macro::Span, 96 }, 97 Fallback(fallback::Span), 98 } 99 100 impl DelimSpan { 101 pub(crate) fn new(group: &imp::Group) -> Self { 102 #[cfg(wrap_proc_macro)] 103 let inner = match group { 104 imp::Group::Compiler(group) => DelimSpanEnum::Compiler { 105 join: group.span(), 106 open: group.span_open(), 107 close: group.span_close(), 108 }, 109 imp::Group::Fallback(group) => DelimSpanEnum::Fallback(group.span()), 110 }; 111 112 #[cfg(not(wrap_proc_macro))] 113 let inner = DelimSpanEnum::Fallback(group.span()); 114 115 DelimSpan { 116 inner, 117 _marker: MARKER, 118 } 119 } 120 121 /// Returns a span covering the entire delimited group. 122 pub fn join(&self) -> Span { 123 match &self.inner { 124 #[cfg(wrap_proc_macro)] 125 DelimSpanEnum::Compiler { join, .. } => Span::_new(imp::Span::Compiler(*join)), 126 DelimSpanEnum::Fallback(span) => Span::_new_fallback(*span), 127 } 128 } 129 130 /// Returns a span for the opening punctuation of the group only. 131 pub fn open(&self) -> Span { 132 match &self.inner { 133 #[cfg(wrap_proc_macro)] 134 DelimSpanEnum::Compiler { open, .. } => Span::_new(imp::Span::Compiler(*open)), 135 DelimSpanEnum::Fallback(span) => Span::_new_fallback(span.first_byte()), 136 } 137 } 138 139 /// Returns a span for the closing punctuation of the group only. 140 pub fn close(&self) -> Span { 141 match &self.inner { 142 #[cfg(wrap_proc_macro)] 143 DelimSpanEnum::Compiler { close, .. } => Span::_new(imp::Span::Compiler(*close)), 144 DelimSpanEnum::Fallback(span) => Span::_new_fallback(span.last_byte()), 145 } 146 } 147 } 148 149 impl Debug for DelimSpan { 150 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 151 Debug::fmt(&self.join(), f) 152 } 153 } 154