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

proc_macro/bridge/
mod.rs
