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};
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);
proc_macro/bridge/mod.rs

proc_macro/bridge/
mod.rs
