1//! Internal interface for communicating between a `proc_macro` client
2//! (a proc macro crate) and a `proc_macro` server (a compiler front-end).
3//!
4//! Serialization (with C ABI buffers) and unique integer handles are employed
5//! to allow safely interfacing between two copies of `proc_macro` built
6//! (from the same source) by different compilers with potentially mismatching
7//! Rust ABIs (e.g., stage0/bin/rustc vs stage1/bin/rustc during bootstrap).
8
9#![deny(unsafe_code)]
10
11use std::hash::Hash;
12use std::ops::{Bound, Range};
13use std::sync::Once;
14use std::{fmt, marker, mem, panic, thread};
15
16use crate::{Delimiter, Level};
17
18/// Higher-order macro describing the server RPC API, allowing automatic
19/// generation of type-safe Rust APIs, both client-side and server-side.
20///
21/// `with_api!(MySelf, my_macro)` expands to:
22/// ```rust,ignore (pseudo-code)
23/// my_macro! {
24/// fn lit_character(ch: char) -> MySelf::Literal;
25/// fn lit_span(lit: &MySelf::Literal) -> MySelf::Span;
26/// fn lit_set_span(lit: &mut MySelf::Literal, span: MySelf::Span);
27/// // ...
28/// }
29/// ```
30///
31/// The first argument serves to customize the argument/return types,
32/// to enable several different usecases:
33///
34/// If `MySelf` is just `Self`, then the types are only valid inside
35/// a trait or a trait impl, where the trait has associated types
36/// for each of the API types. If non-associated types are desired,
37/// a module name (`self` in practice) can be used instead of `Self`.
38macro_rules! with_api {
39 ($S:ident, $m:ident) => {
40 $m! {
41 fn injected_env_var(var: &str) -> Option<String>;
42 fn track_env_var(var: &str, value: Option<&str>);
43 fn track_path(path: &str);
44 fn literal_from_str(s: &str) -> Result<Literal<$S::Span, $S::Symbol>, ()>;
45 fn emit_diagnostic(diagnostic: Diagnostic<$S::Span>);
46
47 fn ts_drop(stream: $S::TokenStream);
48 fn ts_clone(stream: &$S::TokenStream) -> $S::TokenStream;
49 fn ts_is_empty(stream: &$S::TokenStream) -> bool;
50 fn ts_expand_expr(stream: &$S::TokenStream) -> Result<$S::TokenStream, ()>;
51 fn ts_from_str(src: &str) -> $S::TokenStream;
52 fn ts_to_string(stream: &$S::TokenStream) -> String;
53 fn ts_from_token_tree(
54 tree: TokenTree<$S::TokenStream, $S::Span, $S::Symbol>,
55 ) -> $S::TokenStream;
56 fn ts_concat_trees(
57 base: Option<$S::TokenStream>,
58 trees: Vec<TokenTree<$S::TokenStream, $S::Span, $S::Symbol>>,
59 ) -> $S::TokenStream;
60 fn ts_concat_streams(
61 base: Option<$S::TokenStream>,
62 streams: Vec<$S::TokenStream>,
63 ) -> $S::TokenStream;
64 fn ts_into_trees(
65 stream: $S::TokenStream
66 ) -> Vec<TokenTree<$S::TokenStream, $S::Span, $S::Symbol>>;
67
68 fn span_debug(span: $S::Span) -> String;
69 fn span_parent(span: $S::Span) -> Option<$S::Span>;
70 fn span_source(span: $S::Span) -> $S::Span;
71 fn span_byte_range(span: $S::Span) -> Range<usize>;
72 fn span_start(span: $S::Span) -> $S::Span;
73 fn span_end(span: $S::Span) -> $S::Span;
74 fn span_line(span: $S::Span) -> usize;
75 fn span_column(span: $S::Span) -> usize;
76 fn span_file(span: $S::Span) -> String;
77 fn span_local_file(span: $S::Span) -> Option<String>;
78 fn span_join(span: $S::Span, other: $S::Span) -> Option<$S::Span>;
79 fn span_subspan(span: $S::Span, start: Bound<usize>, end: Bound<usize>) -> Option<$S::Span>;
80 fn span_resolved_at(span: $S::Span, at: $S::Span) -> $S::Span;
81 fn span_source_text(span: $S::Span) -> Option<String>;
82 fn span_save_span(span: $S::Span) -> usize;
83 fn span_recover_proc_macro_span(id: usize) -> $S::Span;
84
85 fn symbol_normalize_and_validate_ident(string: &str) -> Result<$S::Symbol, ()>;
86 }
87 };
88}
89
90pub(crate) struct Methods;
91
92#[allow(unsafe_code)]
93mod arena;
94#[allow(unsafe_code)]
95mod buffer;
96#[deny(unsafe_code)]
97pub mod client;
98#[allow(unsafe_code)]
99mod closure;
100#[forbid(unsafe_code)]
101mod fxhash;
102#[forbid(unsafe_code)]
103mod handle;
104#[macro_use]
105#[forbid(unsafe_code)]
106mod rpc;
107#[allow(unsafe_code)]
108mod selfless_reify;
109#[forbid(unsafe_code)]
110pub mod server;
111#[allow(unsafe_code)]
112mod symbol;
113
114use buffer::Buffer;
115pub use rpc::PanicMessage;
116use rpc::{Decode, Encode};
117
118/// Configuration for establishing an active connection between a server and a
119/// client. The server creates the bridge config (`run_server` in `server.rs`),
120/// then passes it to the client through the function pointer in the `run` field
121/// of `client::Client`. The client constructs a local `Bridge` from the config
122/// in TLS during its execution (`Bridge::{enter, with}` in `client.rs`).
123#[repr(C)]
124pub struct BridgeConfig<'a> {
125 /// Buffer used to pass initial input to the client.
126 input: Buffer,
127
128 /// Server-side function that the client uses to make requests.
129 dispatch: closure::Closure<'a, Buffer, Buffer>,
130
131 /// If 'true', always invoke the default panic hook
132 force_show_panics: bool,
133}
134
135impl !Send for BridgeConfig<'_> {}
136impl !Sync for BridgeConfig<'_> {}
137
138macro_rules! declare_tags {
139 (
140 $(fn $method:ident($($arg:ident: $arg_ty:ty),* $(,)?) $(-> $ret_ty:ty)*;)*
141 ) => {
142 #[allow(non_camel_case_types)]
143 pub(super) enum ApiTags {
144 $($method),*
145 }
146 rpc_encode_decode!(enum ApiTags { $($method),* });
147 }
148}
149with_api!(self, declare_tags);
150
151/// Helper to wrap associated types to allow trait impl dispatch.
152/// That is, normally a pair of impls for `T::Foo` and `T::Bar`
153/// can overlap, but if the impls are, instead, on types like
154/// `Marked<T::Foo, Foo>` and `Marked<T::Bar, Bar>`, they can't.
155trait Mark {
156 type Unmarked;
157 fn mark(unmarked: Self::Unmarked) -> Self;
158 fn unmark(self) -> Self::Unmarked;
159}
160
161#[derive(Copy, Clone, PartialEq, Eq, Hash)]
162struct Marked<T, M> {
163 value: T,
164 _marker: marker::PhantomData<M>,
165}
166
167impl<T, M> Mark for Marked<T, M> {
168 type Unmarked = T;
169 fn mark(unmarked: Self::Unmarked) -> Self {
170 Marked { value: unmarked, _marker: marker::PhantomData }
171 }
172 fn unmark(self) -> Self::Unmarked {
173 self.value
174 }
175}
176impl<'a, T, M> Mark for &'a Marked<T, M> {
177 type Unmarked = &'a T;
178 fn mark(_: Self::Unmarked) -> Self {
179 unreachable!()
180 }
181 fn unmark(self) -> Self::Unmarked {
182 &self.value
183 }
184}
185
186impl<T: Mark> Mark for Vec<T> {
187 type Unmarked = Vec<T::Unmarked>;
188 fn mark(unmarked: Self::Unmarked) -> Self {
189 // Should be a no-op due to std's in-place collect optimizations.
190 unmarked.into_iter().map(T::mark).collect()
191 }
192 fn unmark(self) -> Self::Unmarked {
193 // Should be a no-op due to std's in-place collect optimizations.
194 self.into_iter().map(T::unmark).collect()
195 }
196}
197
198macro_rules! mark_noop {
199 ($($ty:ty),* $(,)?) => {
200 $(
201 impl Mark for $ty {
202 type Unmarked = Self;
203 fn mark(unmarked: Self::Unmarked) -> Self {
204 unmarked
205 }
206 fn unmark(self) -> Self::Unmarked {
207 self
208 }
209 }
210 )*
211 }
212}
213mark_noop! {
214 (),
215 bool,
216 &'_ str,
217 String,
218 u8,
219 usize,
220 Delimiter,
221 LitKind,
222 Level,
223}
224
225rpc_encode_decode!(
226 enum Delimiter {
227 Parenthesis,
228 Brace,
229 Bracket,
230 None,
231 }
232);
233rpc_encode_decode!(
234 enum Level {
235 Error,
236 Warning,
237 Note,
238 Help,
239 }
240);
241
242#[derive(Copy, Clone, Eq, PartialEq, Debug)]
243pub enum LitKind {
244 Byte,
245 Char,
246 Integer,
247 Float,
248 Str,
249 StrRaw(u8),
250 ByteStr,
251 ByteStrRaw(u8),
252 CStr,
253 CStrRaw(u8),
254 // This should have an `ErrorGuaranteed`, except that type isn't available
255 // in this crate. (Imagine it is there.) Hence the `WithGuar` suffix. Must
256 // only be constructed in `LitKind::from_internal`, where an
257 // `ErrorGuaranteed` is available.
258 ErrWithGuar,
259}
260
261rpc_encode_decode!(
262 enum LitKind {
263 Byte,
264 Char,
265 Integer,
266 Float,
267 Str,
268 StrRaw(n),
269 ByteStr,
270 ByteStrRaw(n),
271 CStr,
272 CStrRaw(n),
273 ErrWithGuar,
274 }
275);
276
277macro_rules! mark_compound {
278 (struct $name:ident <$($T:ident),+> { $($field:ident),* $(,)? }) => {
279 impl<$($T: Mark),+> Mark for $name <$($T),+> {
280 type Unmarked = $name <$($T::Unmarked),+>;
281 fn mark(unmarked: Self::Unmarked) -> Self {
282 $name {
283 $($field: Mark::mark(unmarked.$field)),*
284 }
285 }
286 fn unmark(self) -> Self::Unmarked {
287 $name {
288 $($field: Mark::unmark(self.$field)),*
289 }
290 }
291 }
292 };
293 (enum $name:ident <$($T:ident),+> { $($variant:ident $(($field:ident))?),* $(,)? }) => {
294 impl<$($T: Mark),+> Mark for $name <$($T),+> {
295 type Unmarked = $name <$($T::Unmarked),+>;
296 fn mark(unmarked: Self::Unmarked) -> Self {
297 match unmarked {
298 $($name::$variant $(($field))? => {
299 $name::$variant $((Mark::mark($field)))?
300 })*
301 }
302 }
303 fn unmark(self) -> Self::Unmarked {
304 match self {
305 $($name::$variant $(($field))? => {
306 $name::$variant $((Mark::unmark($field)))?
307 })*
308 }
309 }
310 }
311 }
312}
313
314macro_rules! compound_traits {
315 ($($t:tt)*) => {
316 rpc_encode_decode!($($t)*);
317 mark_compound!($($t)*);
318 };
319}
320
321compound_traits!(
322 enum Bound<T> {
323 Included(x),
324 Excluded(x),
325 Unbounded,
326 }
327);
328
329compound_traits!(
330 enum Option<T> {
331 Some(t),
332 None,
333 }
334);
335
336compound_traits!(
337 enum Result<T, E> {
338 Ok(t),
339 Err(e),
340 }
341);
342
343#[derive(Copy, Clone)]
344pub struct DelimSpan<Span> {
345 pub open: Span,
346 pub close: Span,
347 pub entire: Span,
348}
349
350impl<Span: Copy> DelimSpan<Span> {
351 pub fn from_single(span: Span) -> Self {
352 DelimSpan { open: span, close: span, entire: span }
353 }
354}
355
356compound_traits!(struct DelimSpan<Span> { open, close, entire });
357
358#[derive(Clone)]
359pub struct Group<TokenStream, Span> {
360 pub delimiter: Delimiter,
361 pub stream: Option<TokenStream>,
362 pub span: DelimSpan<Span>,
363}
364
365compound_traits!(struct Group<TokenStream, Span> { delimiter, stream, span });
366
367#[derive(Clone)]
368pub struct Punct<Span> {
369 pub ch: u8,
370 pub joint: bool,
371 pub span: Span,
372}
373
374compound_traits!(struct Punct<Span> { ch, joint, span });
375
376#[derive(Copy, Clone, Eq, PartialEq)]
377pub struct Ident<Span, Symbol> {
378 pub sym: Symbol,
379 pub is_raw: bool,
380 pub span: Span,
381}
382
383compound_traits!(struct Ident<Span, Symbol> { sym, is_raw, span });
384
385#[derive(Clone, Eq, PartialEq)]
386pub struct Literal<Span, Symbol> {
387 pub kind: LitKind,
388 pub symbol: Symbol,
389 pub suffix: Option<Symbol>,
390 pub span: Span,
391}
392
393compound_traits!(struct Literal<Sp, Sy> { kind, symbol, suffix, span });
394
395#[derive(Clone)]
396pub enum TokenTree<TokenStream, Span, Symbol> {
397 Group(Group<TokenStream, Span>),
398 Punct(Punct<Span>),
399 Ident(Ident<Span, Symbol>),
400 Literal(Literal<Span, Symbol>),
401}
402
403compound_traits!(
404 enum TokenTree<TokenStream, Span, Symbol> {
405 Group(tt),
406 Punct(tt),
407 Ident(tt),
408 Literal(tt),
409 }
410);
411
412#[derive(Clone, Debug)]
413pub struct Diagnostic<Span> {
414 pub level: Level,
415 pub message: String,
416 pub spans: Vec<Span>,
417 pub children: Vec<Diagnostic<Span>>,
418}
419
420compound_traits!(
421 struct Diagnostic<Span> { level, message, spans, children }
422);
423
424/// Globals provided alongside the initial inputs for a macro expansion.
425/// Provides values such as spans which are used frequently to avoid RPC.
426#[derive(Clone)]
427pub struct ExpnGlobals<Span> {
428 pub def_site: Span,
429 pub call_site: Span,
430 pub mixed_site: Span,
431}
432
433compound_traits!(
434 struct ExpnGlobals<Span> { def_site, call_site, mixed_site }
435);
436
437compound_traits!(
438 struct Range<T> { start, end }
439);
440