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