proc_macro/bridge/
mod.rs

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// proc_macros anyway don't work on wasm hosts so while both sides of this bridge can
11// be built with different versions of rustc, the wasm ABI changes don't really matter.
12#![allow(wasm_c_abi)]
13
14use std::hash::Hash;
15use std::ops::{Bound, Range};
16use std::sync::Once;
17use std::{fmt, marker, mem, panic, thread};
18
19use crate::{Delimiter, Level, Spacing};
20
21/// Higher-order macro describing the server RPC API, allowing automatic
22/// generation of type-safe Rust APIs, both client-side and server-side.
23///
24/// `with_api!(MySelf, my_self, my_macro)` expands to:
25/// ```rust,ignore (pseudo-code)
26/// my_macro! {
27///     // ...
28///     Literal {
29///         // ...
30///         fn character(ch: char) -> MySelf::Literal;
31///         // ...
32///         fn span(my_self: &MySelf::Literal) -> MySelf::Span;
33///         fn set_span(my_self: &mut MySelf::Literal, span: MySelf::Span);
34///     },
35///     // ...
36/// }
37/// ```
38///
39/// The first two arguments serve to customize the arguments names
40/// and argument/return types, to enable several different usecases:
41///
42/// If `my_self` is just `self`, then each `fn` signature can be used
43/// as-is for a method. If it's anything else (`self_` in practice),
44/// then the signatures don't have a special `self` argument, and
45/// can, therefore, have a different one introduced.
46///
47/// If `MySelf` is just `Self`, then the types are only valid inside
48/// a trait or a trait impl, where the trait has associated types
49/// for each of the API types. If non-associated types are desired,
50/// a module name (`self` in practice) can be used instead of `Self`.
51macro_rules! with_api {
52    ($S:ident, $self:ident, $m:ident) => {
53        $m! {
54            FreeFunctions {
55                fn drop($self: $S::FreeFunctions);
56                fn injected_env_var(var: &str) -> Option<String>;
57                fn track_env_var(var: &str, value: Option<&str>);
58                fn track_path(path: &str);
59                fn literal_from_str(s: &str) -> Result<Literal<$S::Span, $S::Symbol>, ()>;
60                fn emit_diagnostic(diagnostic: Diagnostic<$S::Span>);
61            },
62            TokenStream {
63                fn drop($self: $S::TokenStream);
64                fn clone($self: &$S::TokenStream) -> $S::TokenStream;
65                fn is_empty($self: &$S::TokenStream) -> bool;
66                fn expand_expr($self: &$S::TokenStream) -> Result<$S::TokenStream, ()>;
67                fn from_str(src: &str) -> $S::TokenStream;
68                fn to_string($self: &$S::TokenStream) -> String;
69                fn from_token_tree(
70                    tree: TokenTree<$S::TokenStream, $S::Span, $S::Symbol>,
71                ) -> $S::TokenStream;
72                fn concat_trees(
73                    base: Option<$S::TokenStream>,
74                    trees: Vec<TokenTree<$S::TokenStream, $S::Span, $S::Symbol>>,
75                ) -> $S::TokenStream;
76                fn concat_streams(
77                    base: Option<$S::TokenStream>,
78                    streams: Vec<$S::TokenStream>,
79                ) -> $S::TokenStream;
80                fn into_trees(
81                    $self: $S::TokenStream
82                ) -> Vec<TokenTree<$S::TokenStream, $S::Span, $S::Symbol>>;
83            },
84            SourceFile {
85                fn drop($self: $S::SourceFile);
86                fn clone($self: &$S::SourceFile) -> $S::SourceFile;
87                fn eq($self: &$S::SourceFile, other: &$S::SourceFile) -> bool;
88                fn path($self: &$S::SourceFile) -> String;
89                fn is_real($self: &$S::SourceFile) -> bool;
90            },
91            Span {
92                fn debug($self: $S::Span) -> String;
93                fn source_file($self: $S::Span) -> $S::SourceFile;
94                fn parent($self: $S::Span) -> Option<$S::Span>;
95                fn source($self: $S::Span) -> $S::Span;
96                fn byte_range($self: $S::Span) -> Range<usize>;
97                fn start($self: $S::Span) -> $S::Span;
98                fn end($self: $S::Span) -> $S::Span;
99                fn line($self: $S::Span) -> usize;
100                fn column($self: $S::Span) -> usize;
101                fn join($self: $S::Span, other: $S::Span) -> Option<$S::Span>;
102                fn subspan($self: $S::Span, start: Bound<usize>, end: Bound<usize>) -> Option<$S::Span>;
103                fn resolved_at($self: $S::Span, at: $S::Span) -> $S::Span;
104                fn source_text($self: $S::Span) -> Option<String>;
105                fn save_span($self: $S::Span) -> usize;
106                fn recover_proc_macro_span(id: usize) -> $S::Span;
107            },
108            Symbol {
109                fn normalize_and_validate_ident(string: &str) -> Result<$S::Symbol, ()>;
110            },
111        }
112    };
113}
114
115// Similar to `with_api`, but only lists the types requiring handles, and they
116// are divided into the two storage categories.
117macro_rules! with_api_handle_types {
118    ($m:ident) => {
119        $m! {
120            'owned:
121            FreeFunctions,
122            TokenStream,
123            SourceFile,
124
125            'interned:
126            Span,
127            // Symbol is handled manually
128        }
129    };
130}
131
132// FIXME(eddyb) this calls `encode` for each argument, but in reverse,
133// to match the ordering in `reverse_decode`.
134macro_rules! reverse_encode {
135    ($writer:ident;) => {};
136    ($writer:ident; $first:ident $(, $rest:ident)*) => {
137        reverse_encode!($writer; $($rest),*);
138        $first.encode(&mut $writer, &mut ());
139    }
140}
141
142// FIXME(eddyb) this calls `decode` for each argument, but in reverse,
143// to avoid borrow conflicts from borrows started by `&mut` arguments.
144macro_rules! reverse_decode {
145    ($reader:ident, $s:ident;) => {};
146    ($reader:ident, $s:ident; $first:ident: $first_ty:ty $(, $rest:ident: $rest_ty:ty)*) => {
147        reverse_decode!($reader, $s; $($rest: $rest_ty),*);
148        let $first = <$first_ty>::decode(&mut $reader, $s);
149    }
150}
151
152#[allow(unsafe_code)]
153mod arena;
154#[allow(unsafe_code)]
155mod buffer;
156#[deny(unsafe_code)]
157pub mod client;
158#[allow(unsafe_code)]
159mod closure;
160#[forbid(unsafe_code)]
161mod fxhash;
162#[forbid(unsafe_code)]
163mod handle;
164#[macro_use]
165#[forbid(unsafe_code)]
166mod rpc;
167#[allow(unsafe_code)]
168mod selfless_reify;
169#[forbid(unsafe_code)]
170pub mod server;
171#[allow(unsafe_code)]
172mod symbol;
173
174use buffer::Buffer;
175pub use rpc::PanicMessage;
176use rpc::{Decode, DecodeMut, Encode, Reader, Writer};
177
178/// Configuration for establishing an active connection between a server and a
179/// client.  The server creates the bridge config (`run_server` in `server.rs`),
180/// then passes it to the client through the function pointer in the `run` field
181/// of `client::Client`. The client constructs a local `Bridge` from the config
182/// in TLS during its execution (`Bridge::{enter, with}` in `client.rs`).
183#[repr(C)]
184pub struct BridgeConfig<'a> {
185    /// Buffer used to pass initial input to the client.
186    input: Buffer,
187
188    /// Server-side function that the client uses to make requests.
189    dispatch: closure::Closure<'a, Buffer, Buffer>,
190
191    /// If 'true', always invoke the default panic hook
192    force_show_panics: bool,
193
194    // Prevent Send and Sync impls. `!Send`/`!Sync` is the usual way of doing
195    // this, but that requires unstable features. rust-analyzer uses this code
196    // and avoids unstable features.
197    _marker: marker::PhantomData<*mut ()>,
198}
199
200#[forbid(unsafe_code)]
201#[allow(non_camel_case_types)]
202mod api_tags {
203    use super::rpc::{DecodeMut, Encode, Reader, Writer};
204
205    macro_rules! declare_tags {
206        ($($name:ident {
207            $(fn $method:ident($($arg:ident: $arg_ty:ty),* $(,)?) $(-> $ret_ty:ty)*;)*
208        }),* $(,)?) => {
209            $(
210                pub(super) enum $name {
211                    $($method),*
212                }
213                rpc_encode_decode!(enum $name { $($method),* });
214            )*
215
216            pub(super) enum Method {
217                $($name($name)),*
218            }
219            rpc_encode_decode!(enum Method { $($name(m)),* });
220        }
221    }
222    with_api!(self, self, declare_tags);
223}
224
225/// Helper to wrap associated types to allow trait impl dispatch.
226/// That is, normally a pair of impls for `T::Foo` and `T::Bar`
227/// can overlap, but if the impls are, instead, on types like
228/// `Marked<T::Foo, Foo>` and `Marked<T::Bar, Bar>`, they can't.
229trait Mark {
230    type Unmarked;
231    fn mark(unmarked: Self::Unmarked) -> Self;
232}
233
234/// Unwrap types wrapped by `Mark::mark` (see `Mark` for details).
235trait Unmark {
236    type Unmarked;
237    fn unmark(self) -> Self::Unmarked;
238}
239
240#[derive(Copy, Clone, PartialEq, Eq, Hash)]
241struct Marked<T, M> {
242    value: T,
243    _marker: marker::PhantomData<M>,
244}
245
246impl<T, M> Mark for Marked<T, M> {
247    type Unmarked = T;
248    fn mark(unmarked: Self::Unmarked) -> Self {
249        Marked { value: unmarked, _marker: marker::PhantomData }
250    }
251}
252impl<T, M> Unmark for Marked<T, M> {
253    type Unmarked = T;
254    fn unmark(self) -> Self::Unmarked {
255        self.value
256    }
257}
258impl<'a, T, M> Unmark for &'a Marked<T, M> {
259    type Unmarked = &'a T;
260    fn unmark(self) -> Self::Unmarked {
261        &self.value
262    }
263}
264impl<'a, T, M> Unmark for &'a mut Marked<T, M> {
265    type Unmarked = &'a mut T;
266    fn unmark(self) -> Self::Unmarked {
267        &mut self.value
268    }
269}
270
271impl<T: Mark> Mark for Vec<T> {
272    type Unmarked = Vec<T::Unmarked>;
273    fn mark(unmarked: Self::Unmarked) -> Self {
274        // Should be a no-op due to std's in-place collect optimizations.
275        unmarked.into_iter().map(T::mark).collect()
276    }
277}
278impl<T: Unmark> Unmark for Vec<T> {
279    type Unmarked = Vec<T::Unmarked>;
280    fn unmark(self) -> Self::Unmarked {
281        // Should be a no-op due to std's in-place collect optimizations.
282        self.into_iter().map(T::unmark).collect()
283    }
284}
285
286macro_rules! mark_noop {
287    ($($ty:ty),* $(,)?) => {
288        $(
289            impl Mark for $ty {
290                type Unmarked = Self;
291                fn mark(unmarked: Self::Unmarked) -> Self {
292                    unmarked
293                }
294            }
295            impl Unmark for $ty {
296                type Unmarked = Self;
297                fn unmark(self) -> Self::Unmarked {
298                    self
299                }
300            }
301        )*
302    }
303}
304mark_noop! {
305    (),
306    bool,
307    char,
308    &'_ [u8],
309    &'_ str,
310    String,
311    u8,
312    usize,
313    Delimiter,
314    LitKind,
315    Level,
316    Spacing,
317}
318
319rpc_encode_decode!(
320    enum Delimiter {
321        Parenthesis,
322        Brace,
323        Bracket,
324        None,
325    }
326);
327rpc_encode_decode!(
328    enum Level {
329        Error,
330        Warning,
331        Note,
332        Help,
333    }
334);
335rpc_encode_decode!(
336    enum Spacing {
337        Alone,
338        Joint,
339    }
340);
341
342#[derive(Copy, Clone, Eq, PartialEq, Debug)]
343pub enum LitKind {
344    Byte,
345    Char,
346    Integer,
347    Float,
348    Str,
349    StrRaw(u8),
350    ByteStr,
351    ByteStrRaw(u8),
352    CStr,
353    CStrRaw(u8),
354    // This should have an `ErrorGuaranteed`, except that type isn't available
355    // in this crate. (Imagine it is there.) Hence the `WithGuar` suffix. Must
356    // only be constructed in `LitKind::from_internal`, where an
357    // `ErrorGuaranteed` is available.
358    ErrWithGuar,
359}
360
361rpc_encode_decode!(
362    enum LitKind {
363        Byte,
364        Char,
365        Integer,
366        Float,
367        Str,
368        StrRaw(n),
369        ByteStr,
370        ByteStrRaw(n),
371        CStr,
372        CStrRaw(n),
373        ErrWithGuar,
374    }
375);
376
377macro_rules! mark_compound {
378    (struct $name:ident <$($T:ident),+> { $($field:ident),* $(,)? }) => {
379        impl<$($T: Mark),+> Mark for $name <$($T),+> {
380            type Unmarked = $name <$($T::Unmarked),+>;
381            fn mark(unmarked: Self::Unmarked) -> Self {
382                $name {
383                    $($field: Mark::mark(unmarked.$field)),*
384                }
385            }
386        }
387
388        impl<$($T: Unmark),+> Unmark for $name <$($T),+> {
389            type Unmarked = $name <$($T::Unmarked),+>;
390            fn unmark(self) -> Self::Unmarked {
391                $name {
392                    $($field: Unmark::unmark(self.$field)),*
393                }
394            }
395        }
396    };
397    (enum $name:ident <$($T:ident),+> { $($variant:ident $(($field:ident))?),* $(,)? }) => {
398        impl<$($T: Mark),+> Mark for $name <$($T),+> {
399            type Unmarked = $name <$($T::Unmarked),+>;
400            fn mark(unmarked: Self::Unmarked) -> Self {
401                match unmarked {
402                    $($name::$variant $(($field))? => {
403                        $name::$variant $((Mark::mark($field)))?
404                    })*
405                }
406            }
407        }
408
409        impl<$($T: Unmark),+> Unmark for $name <$($T),+> {
410            type Unmarked = $name <$($T::Unmarked),+>;
411            fn unmark(self) -> Self::Unmarked {
412                match self {
413                    $($name::$variant $(($field))? => {
414                        $name::$variant $((Unmark::unmark($field)))?
415                    })*
416                }
417            }
418        }
419    }
420}
421
422macro_rules! compound_traits {
423    ($($t:tt)*) => {
424        rpc_encode_decode!($($t)*);
425        mark_compound!($($t)*);
426    };
427}
428
429compound_traits!(
430    enum Bound<T> {
431        Included(x),
432        Excluded(x),
433        Unbounded,
434    }
435);
436
437compound_traits!(
438    enum Option<T> {
439        Some(t),
440        None,
441    }
442);
443
444compound_traits!(
445    enum Result<T, E> {
446        Ok(t),
447        Err(e),
448    }
449);
450
451#[derive(Copy, Clone)]
452pub struct DelimSpan<Span> {
453    pub open: Span,
454    pub close: Span,
455    pub entire: Span,
456}
457
458impl<Span: Copy> DelimSpan<Span> {
459    pub fn from_single(span: Span) -> Self {
460        DelimSpan { open: span, close: span, entire: span }
461    }
462}
463
464compound_traits!(struct DelimSpan<Span> { open, close, entire });
465
466#[derive(Clone)]
467pub struct Group<TokenStream, Span> {
468    pub delimiter: Delimiter,
469    pub stream: Option<TokenStream>,
470    pub span: DelimSpan<Span>,
471}
472
473compound_traits!(struct Group<TokenStream, Span> { delimiter, stream, span });
474
475#[derive(Clone)]
476pub struct Punct<Span> {
477    pub ch: u8,
478    pub joint: bool,
479    pub span: Span,
480}
481
482compound_traits!(struct Punct<Span> { ch, joint, span });
483
484#[derive(Copy, Clone, Eq, PartialEq)]
485pub struct Ident<Span, Symbol> {
486    pub sym: Symbol,
487    pub is_raw: bool,
488    pub span: Span,
489}
490
491compound_traits!(struct Ident<Span, Symbol> { sym, is_raw, span });
492
493#[derive(Clone, Eq, PartialEq)]
494pub struct Literal<Span, Symbol> {
495    pub kind: LitKind,
496    pub symbol: Symbol,
497    pub suffix: Option<Symbol>,
498    pub span: Span,
499}
500
501compound_traits!(struct Literal<Sp, Sy> { kind, symbol, suffix, span });
502
503#[derive(Clone)]
504pub enum TokenTree<TokenStream, Span, Symbol> {
505    Group(Group<TokenStream, Span>),
506    Punct(Punct<Span>),
507    Ident(Ident<Span, Symbol>),
508    Literal(Literal<Span, Symbol>),
509}
510
511compound_traits!(
512    enum TokenTree<TokenStream, Span, Symbol> {
513        Group(tt),
514        Punct(tt),
515        Ident(tt),
516        Literal(tt),
517    }
518);
519
520#[derive(Clone, Debug)]
521pub struct Diagnostic<Span> {
522    pub level: Level,
523    pub message: String,
524    pub spans: Vec<Span>,
525    pub children: Vec<Diagnostic<Span>>,
526}
527
528compound_traits!(
529    struct Diagnostic<Span> { level, message, spans, children }
530);
531
532/// Globals provided alongside the initial inputs for a macro expansion.
533/// Provides values such as spans which are used frequently to avoid RPC.
534#[derive(Clone)]
535pub struct ExpnGlobals<Span> {
536    pub def_site: Span,
537    pub call_site: Span,
538    pub mixed_site: Span,
539}
540
541compound_traits!(
542    struct ExpnGlobals<Span> { def_site, call_site, mixed_site }
543);
544
545compound_traits!(
546    struct Range<T> { start, end }
547);