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 
11 pub use super::{Delimiter, Level, LineColumn, Spacing};
12 use std::fmt;
13 use std::hash::Hash;
14 use std::marker;
15 use std::mem;
16 use std::ops::Bound;
17 use std::panic;
18 use std::sync::atomic::AtomicUsize;
19 use std::sync::Once;
20 use std::thread;
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`.
52 macro_rules! with_api {
53     ($S:ident, $self:ident, $m:ident) => {
54         $m! {
55             FreeFunctions {
56                 fn drop($self: $S::FreeFunctions);
57                 fn track_env_var(var: &str, value: Option<&str>);
58                 fn track_path(path: &str);
59             },
60             TokenStream {
61                 fn drop($self: $S::TokenStream);
62                 fn clone($self: &$S::TokenStream) -> $S::TokenStream;
63                 fn new() -> $S::TokenStream;
64                 fn is_empty($self: &$S::TokenStream) -> bool;
65                 fn from_str(src: &str) -> $S::TokenStream;
66                 fn to_string($self: &$S::TokenStream) -> String;
67                 fn from_token_tree(
68                     tree: TokenTree<$S::Group, $S::Punct, $S::Ident, $S::Literal>,
69                 ) -> $S::TokenStream;
70                 fn into_iter($self: $S::TokenStream) -> $S::TokenStreamIter;
71             },
72             TokenStreamBuilder {
73                 fn drop($self: $S::TokenStreamBuilder);
74                 fn new() -> $S::TokenStreamBuilder;
75                 fn push($self: &mut $S::TokenStreamBuilder, stream: $S::TokenStream);
76                 fn build($self: $S::TokenStreamBuilder) -> $S::TokenStream;
77             },
78             TokenStreamIter {
79                 fn drop($self: $S::TokenStreamIter);
80                 fn clone($self: &$S::TokenStreamIter) -> $S::TokenStreamIter;
81                 fn next(
82                     $self: &mut $S::TokenStreamIter,
83                 ) -> Option<TokenTree<$S::Group, $S::Punct, $S::Ident, $S::Literal>>;
84             },
85             Group {
86                 fn drop($self: $S::Group);
87                 fn clone($self: &$S::Group) -> $S::Group;
88                 fn new(delimiter: Delimiter, stream: $S::TokenStream) -> $S::Group;
89                 fn delimiter($self: &$S::Group) -> Delimiter;
90                 fn stream($self: &$S::Group) -> $S::TokenStream;
91                 fn span($self: &$S::Group) -> $S::Span;
92                 fn span_open($self: &$S::Group) -> $S::Span;
93                 fn span_close($self: &$S::Group) -> $S::Span;
94                 fn set_span($self: &mut $S::Group, span: $S::Span);
95             },
96             Punct {
97                 fn new(ch: char, spacing: Spacing) -> $S::Punct;
98                 fn as_char($self: $S::Punct) -> char;
99                 fn spacing($self: $S::Punct) -> Spacing;
100                 fn span($self: $S::Punct) -> $S::Span;
101                 fn with_span($self: $S::Punct, span: $S::Span) -> $S::Punct;
102             },
103             Ident {
104                 fn new(string: &str, span: $S::Span, is_raw: bool) -> $S::Ident;
105                 fn span($self: $S::Ident) -> $S::Span;
106                 fn with_span($self: $S::Ident, span: $S::Span) -> $S::Ident;
107             },
108             Literal {
109                 fn drop($self: $S::Literal);
110                 fn clone($self: &$S::Literal) -> $S::Literal;
111                 fn from_str(s: &str) -> Result<$S::Literal, ()>;
112                 fn to_string($self: &$S::Literal) -> String;
113                 fn debug_kind($self: &$S::Literal) -> String;
114                 fn symbol($self: &$S::Literal) -> String;
115                 fn suffix($self: &$S::Literal) -> Option<String>;
116                 fn integer(n: &str) -> $S::Literal;
117                 fn typed_integer(n: &str, kind: &str) -> $S::Literal;
118                 fn float(n: &str) -> $S::Literal;
119                 fn f32(n: &str) -> $S::Literal;
120                 fn f64(n: &str) -> $S::Literal;
121                 fn string(string: &str) -> $S::Literal;
122                 fn character(ch: char) -> $S::Literal;
123                 fn byte_string(bytes: &[u8]) -> $S::Literal;
124                 fn span($self: &$S::Literal) -> $S::Span;
125                 fn set_span($self: &mut $S::Literal, span: $S::Span);
126                 fn subspan(
127                     $self: &$S::Literal,
128                     start: Bound<usize>,
129                     end: Bound<usize>,
130                 ) -> Option<$S::Span>;
131             },
132             SourceFile {
133                 fn drop($self: $S::SourceFile);
134                 fn clone($self: &$S::SourceFile) -> $S::SourceFile;
135                 fn eq($self: &$S::SourceFile, other: &$S::SourceFile) -> bool;
136                 fn path($self: &$S::SourceFile) -> String;
137                 fn is_real($self: &$S::SourceFile) -> bool;
138             },
139             MultiSpan {
140                 fn drop($self: $S::MultiSpan);
141                 fn new() -> $S::MultiSpan;
142                 fn push($self: &mut $S::MultiSpan, span: $S::Span);
143             },
144             Diagnostic {
145                 fn drop($self: $S::Diagnostic);
146                 fn new(level: Level, msg: &str, span: $S::MultiSpan) -> $S::Diagnostic;
147                 fn sub(
148                     $self: &mut $S::Diagnostic,
149                     level: Level,
150                     msg: &str,
151                     span: $S::MultiSpan,
152                 );
153                 fn emit($self: $S::Diagnostic);
154             },
155             Span {
156                 fn debug($self: $S::Span) -> String;
157                 fn def_site() -> $S::Span;
158                 fn call_site() -> $S::Span;
159                 fn mixed_site() -> $S::Span;
160                 fn source_file($self: $S::Span) -> $S::SourceFile;
161                 fn parent($self: $S::Span) -> Option<$S::Span>;
162                 fn source($self: $S::Span) -> $S::Span;
163                 fn start($self: $S::Span) -> LineColumn;
164                 fn end($self: $S::Span) -> LineColumn;
165                 fn join($self: $S::Span, other: $S::Span) -> Option<$S::Span>;
166                 fn resolved_at($self: $S::Span, at: $S::Span) -> $S::Span;
167                 fn source_text($self: $S::Span) -> Option<String>;
168                 fn save_span($self: $S::Span) -> usize;
169                 fn recover_proc_macro_span(id: usize) -> $S::Span;
170             },
171         }
172     };
173 }
174 
175 // FIXME(eddyb) this calls `encode` for each argument, but in reverse,
176 // to avoid borrow conflicts from borrows started by `&mut` arguments.
177 macro_rules! reverse_encode {
178     ($writer:ident;) => {};
179     ($writer:ident; $first:ident $(, $rest:ident)*) => {
180         reverse_encode!($writer; $($rest),*);
181         $first.encode(&mut $writer, &mut ());
182     }
183 }
184 
185 // FIXME(eddyb) this calls `decode` for each argument, but in reverse,
186 // to avoid borrow conflicts from borrows started by `&mut` arguments.
187 macro_rules! reverse_decode {
188     ($reader:ident, $s:ident;) => {};
189     ($reader:ident, $s:ident; $first:ident: $first_ty:ty $(, $rest:ident: $rest_ty:ty)*) => {
190         reverse_decode!($reader, $s; $($rest: $rest_ty),*);
191         let $first = <$first_ty>::decode(&mut $reader, $s);
192     }
193 }
194 
195 #[allow(unsafe_code)]
196 mod buffer;
197 #[forbid(unsafe_code)]
198 pub mod client;
199 #[allow(unsafe_code)]
200 mod closure;
201 #[forbid(unsafe_code)]
202 mod handle;
203 #[macro_use]
204 #[forbid(unsafe_code)]
205 mod rpc;
206 #[allow(unsafe_code)]
207 mod scoped_cell;
208 #[forbid(unsafe_code)]
209 pub mod server;
210 
211 use buffer::Buffer;
212 pub use rpc::PanicMessage;
213 use rpc::{Decode, DecodeMut, Encode, Reader, Writer};
214 
215 /// An active connection between a server and a client.
216 /// The server creates the bridge (`Bridge::run_server` in `server.rs`),
217 /// then passes it to the client through the function pointer in the `run`
218 /// field of `client::Client`. The client holds its copy of the `Bridge`
219 /// in TLS during its execution (`Bridge::{enter, with}` in `client.rs`).
220 #[repr(C)]
221 pub struct Bridge<'a> {
222     /// Reusable buffer (only `clear`-ed, never shrunk), primarily
223     /// used for making requests, but also for passing input to client.
224     cached_buffer: Buffer<u8>,
225 
226     /// Server-side function that the client uses to make requests.
227     dispatch: closure::Closure<'a, Buffer<u8>, Buffer<u8>>,
228 
229     /// If 'true', always invoke the default panic hook
230     force_show_panics: bool,
231 }
232 
233 #[forbid(unsafe_code)]
234 #[allow(non_camel_case_types)]
235 mod api_tags {
236     use super::rpc::{DecodeMut, Encode, Reader, Writer};
237 
238     macro_rules! declare_tags {
239         ($($name:ident {
240             $(fn $method:ident($($arg:ident: $arg_ty:ty),* $(,)?) $(-> $ret_ty:ty)*;)*
241         }),* $(,)?) => {
242             $(
243                 pub(super) enum $name {
244                     $($method),*
245                 }
246                 rpc_encode_decode!(enum $name { $($method),* });
247             )*
248 
249 
250             pub(super) enum Method {
251                 $($name($name)),*
252             }
253             rpc_encode_decode!(enum Method { $($name(m)),* });
254         }
255     }
256     with_api!(self, self, declare_tags);
257 }
258 
259 /// Helper to wrap associated types to allow trait impl dispatch.
260 /// That is, normally a pair of impls for `T::Foo` and `T::Bar`
261 /// can overlap, but if the impls are, instead, on types like
262 /// `Marked<T::Foo, Foo>` and `Marked<T::Bar, Bar>`, they can't.
263 trait Mark {
264     type Unmarked;
mark(unmarked: Self::Unmarked) -> Self265     fn mark(unmarked: Self::Unmarked) -> Self;
266 }
267 
268 /// Unwrap types wrapped by `Mark::mark` (see `Mark` for details).
269 trait Unmark {
270     type Unmarked;
unmark(self) -> Self::Unmarked271     fn unmark(self) -> Self::Unmarked;
272 }
273 
274 #[derive(Copy, Clone, PartialEq, Eq, Hash)]
275 struct Marked<T, M> {
276     value: T,
277     _marker: marker::PhantomData<M>,
278 }
279 
280 impl<T, M> Mark for Marked<T, M> {
281     type Unmarked = T;
mark(unmarked: Self::Unmarked) -> Self282     fn mark(unmarked: Self::Unmarked) -> Self {
283         Marked { value: unmarked, _marker: marker::PhantomData }
284     }
285 }
286 impl<T, M> Unmark for Marked<T, M> {
287     type Unmarked = T;
unmark(self) -> Self::Unmarked288     fn unmark(self) -> Self::Unmarked {
289         self.value
290     }
291 }
292 impl<'a, T, M> Unmark for &'a Marked<T, M> {
293     type Unmarked = &'a T;
unmark(self) -> Self::Unmarked294     fn unmark(self) -> Self::Unmarked {
295         &self.value
296     }
297 }
298 impl<'a, T, M> Unmark for &'a mut Marked<T, M> {
299     type Unmarked = &'a mut T;
unmark(self) -> Self::Unmarked300     fn unmark(self) -> Self::Unmarked {
301         &mut self.value
302     }
303 }
304 
305 impl<T: Mark> Mark for Option<T> {
306     type Unmarked = Option<T::Unmarked>;
mark(unmarked: Self::Unmarked) -> Self307     fn mark(unmarked: Self::Unmarked) -> Self {
308         unmarked.map(T::mark)
309     }
310 }
311 impl<T: Unmark> Unmark for Option<T> {
312     type Unmarked = Option<T::Unmarked>;
unmark(self) -> Self::Unmarked313     fn unmark(self) -> Self::Unmarked {
314         self.map(T::unmark)
315     }
316 }
317 
318 impl<T: Mark, E: Mark> Mark for Result<T, E> {
319     type Unmarked = Result<T::Unmarked, E::Unmarked>;
mark(unmarked: Self::Unmarked) -> Self320     fn mark(unmarked: Self::Unmarked) -> Self {
321         unmarked.map(T::mark).map_err(E::mark)
322     }
323 }
324 impl<T: Unmark, E: Unmark> Unmark for Result<T, E> {
325     type Unmarked = Result<T::Unmarked, E::Unmarked>;
unmark(self) -> Self::Unmarked326     fn unmark(self) -> Self::Unmarked {
327         self.map(T::unmark).map_err(E::unmark)
328     }
329 }
330 
331 macro_rules! mark_noop {
332     ($($ty:ty),* $(,)?) => {
333         $(
334             impl Mark for $ty {
335                 type Unmarked = Self;
336                 fn mark(unmarked: Self::Unmarked) -> Self {
337                     unmarked
338                 }
339             }
340             impl Unmark for $ty {
341                 type Unmarked = Self;
342                 fn unmark(self) -> Self::Unmarked {
343                     self
344                 }
345             }
346         )*
347     }
348 }
349 mark_noop! {
350     (),
351     bool,
352     char,
353     &'_ [u8],
354     &'_ str,
355     String,
356     usize,
357     Delimiter,
358     Level,
359     LineColumn,
360     Spacing,
361     Bound<usize>,
362 }
363 
364 rpc_encode_decode!(
365     enum Delimiter {
366         Parenthesis,
367         Brace,
368         Bracket,
369         None,
370     }
371 );
372 rpc_encode_decode!(
373     enum Level {
374         Error,
375         Warning,
376         Note,
377         Help,
378     }
379 );
380 rpc_encode_decode!(struct LineColumn { line, column });
381 rpc_encode_decode!(
382     enum Spacing {
383         Alone,
384         Joint,
385     }
386 );
387 
388 #[derive(Clone)]
389 pub enum TokenTree<G, P, I, L> {
390     Group(G),
391     Punct(P),
392     Ident(I),
393     Literal(L),
394 }
395 
396 impl<G: Mark, P: Mark, I: Mark, L: Mark> Mark for TokenTree<G, P, I, L> {
397     type Unmarked = TokenTree<G::Unmarked, P::Unmarked, I::Unmarked, L::Unmarked>;
mark(unmarked: Self::Unmarked) -> Self398     fn mark(unmarked: Self::Unmarked) -> Self {
399         match unmarked {
400             TokenTree::Group(tt) => TokenTree::Group(G::mark(tt)),
401             TokenTree::Punct(tt) => TokenTree::Punct(P::mark(tt)),
402             TokenTree::Ident(tt) => TokenTree::Ident(I::mark(tt)),
403             TokenTree::Literal(tt) => TokenTree::Literal(L::mark(tt)),
404         }
405     }
406 }
407 impl<G: Unmark, P: Unmark, I: Unmark, L: Unmark> Unmark for TokenTree<G, P, I, L> {
408     type Unmarked = TokenTree<G::Unmarked, P::Unmarked, I::Unmarked, L::Unmarked>;
unmark(self) -> Self::Unmarked409     fn unmark(self) -> Self::Unmarked {
410         match self {
411             TokenTree::Group(tt) => TokenTree::Group(tt.unmark()),
412             TokenTree::Punct(tt) => TokenTree::Punct(tt.unmark()),
413             TokenTree::Ident(tt) => TokenTree::Ident(tt.unmark()),
414             TokenTree::Literal(tt) => TokenTree::Literal(tt.unmark()),
415         }
416     }
417 }
418 
419 rpc_encode_decode!(
420     enum TokenTree<G, P, I, L> {
421         Group(tt),
422         Punct(tt),
423         Ident(tt),
424         Literal(tt),
425     }
426 );
427