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

rustc_proc_macro/bridge/
mod.rs
