mod.rs - source
Description: Source of the Rust file `library/proc_macro/src/bridge/mod.rs`.

#
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#[allow(unsafe_code)]
    123mod arena;
    124#[allow(unsafe_code)]
    125mod buffer;
    126#[deny(unsafe_code)]
    127pub mod client;
    128#[allow(unsafe_code)]
    129mod closure;
    130#[forbid(unsafe_code)]
    131mod fxhash;
    132#[forbid(unsafe_code)]
    133mod handle;
    134#[macro_use]
    135#[forbid(unsafe_code)]
    136mod rpc;
    137#[allow(unsafe_code)]
    138mod selfless_reify;
    139#[forbid(unsafe_code)]
    140pub mod server;
    141#[allow(unsafe_code)]
    142mod symbol;
    143
    144use buffer::Buffer;
    145pub use rpc::PanicMessage;
    146use rpc::{Decode, Encode, Reader, Writer};
    147
    148/// Configuration for establishing an active connection between a server and a
    149/// client.  The server creates the bridge config (`run_server` in `server.rs`),
    150/// then passes it to the client through the function pointer in the `run` field
    151/// of `client::Client`. The client constructs a local `Bridge` from the config
    152/// in TLS during its execution (`Bridge::{enter, with}` in `client.rs`).
    153#[repr(C)]
    154pub struct BridgeConfig<'a> {
    155    /// Buffer used to pass initial input to the client.
    156    input: Buffer,
    157
    158    /// Server-side function that the client uses to make requests.
    159    dispatch: closure::Closure<'a, Buffer, Buffer>,
    160
    161    /// If 'true', always invoke the default panic hook
    162    force_show_panics: bool,
    163}
    164
    165impl !Send for BridgeConfig<'_> {}
    166impl !Sync for BridgeConfig<'_> {}
    167
    168#[forbid(unsafe_code)]
    169#[allow(non_camel_case_types)]
    170mod api_tags {
    171    use super::rpc::{Decode, Encode, Reader, Writer};
    172
    173    macro_rules! declare_tags {
    174        ($($name:ident {
    175            $(fn $method:ident($($arg:ident: $arg_ty:ty),* $(,)?) $(-> $ret_ty:ty)*;)*
    176        }),* $(,)?) => {
    177            $(
    178                pub(super) enum $name {
    179                    $($method),*
    180                }
    181                rpc_encode_decode!(enum $name { $($method),* });
    182            )*
    183
    184            pub(super) enum Method {
    185                $($name($name)),*
    186            }
    187            rpc_encode_decode!(enum Method { $($name(m)),* });
    188        }
    189    }
    190    with_api!(self, self, declare_tags);
    191}
    192
    193/// Helper to wrap associated types to allow trait impl dispatch.
    194/// That is, normally a pair of impls for `T::Foo` and `T::Bar`
    195/// can overlap, but if the impls are, instead, on types like
    196/// `Marked<T::Foo, Foo>` and `Marked<T::Bar, Bar>`, they can't.
    197trait Mark {
    198    type Unmarked;
    199    fn mark(unmarked: Self::Unmarked) -> Self;
    200}
    201
    202/// Unwrap types wrapped by `Mark::mark` (see `Mark` for details).
    203trait Unmark {
    204    type Unmarked;
    205    fn unmark(self) -> Self::Unmarked;
    206}
    207
    208#[derive(Copy, Clone, PartialEq, Eq, Hash)]
    209struct Marked<T, M> {
    210    value: T,
    211    _marker: marker::PhantomData<M>,
    212}
    213
    214impl<T, M> Mark for Marked<T, M> {
    215    type Unmarked = T;
    216    fn mark(unmarked: Self::Unmarked) -> Self {
    217        Marked { value: unmarked, _marker: marker::PhantomData }
    218    }
    219}
    220impl<T, M> Unmark for Marked<T, M> {
    221    type Unmarked = T;
    222    fn unmark(self) -> Self::Unmarked {
    223        self.value
    224    }
    225}
    226impl<'a, T, M> Unmark for &'a Marked<T, M> {
    227    type Unmarked = &'a T;
    228    fn unmark(self) -> Self::Unmarked {
    229        &self.value
    230    }
    231}
    232impl<'a, T, M> Unmark for &'a mut Marked<T, M> {
    233    type Unmarked = &'a mut T;
    234    fn unmark(self) -> Self::Unmarked {
    235        &mut self.value
    236    }
    237}
    238
    239impl<T: Mark> Mark for Vec<T> {
    240    type Unmarked = Vec<T::Unmarked>;
    241    fn mark(unmarked: Self::Unmarked) -> Self {
    242        // Should be a no-op due to std's in-place collect optimizations.
    243        unmarked.into_iter().map(T::mark).collect()
    244    }
    245}
    246impl<T: Unmark> Unmark for Vec<T> {
    247    type Unmarked = Vec<T::Unmarked>;
    248    fn unmark(self) -> Self::Unmarked {
    249        // Should be a no-op due to std's in-place collect optimizations.
    250        self.into_iter().map(T::unmark).collect()
    251    }
    252}
    253
    254macro_rules! mark_noop {
    255    ($($ty:ty),* $(,)?) => {
    256        $(
    257            impl Mark for $ty {
    258                type Unmarked = Self;
    259                fn mark(unmarked: Self::Unmarked) -> Self {
    260                    unmarked
    261                }
    262            }
    263            impl Unmark for $ty {
    264                type Unmarked = Self;
    265                fn unmark(self) -> Self::Unmarked {
    266                    self
    267                }
    268            }
    269        )*
    270    }
    271}
    272mark_noop! {
    273    (),
    274    bool,
    275    char,
    276    &'_ [u8],
    277    &'_ str,
    278    String,
    279    u8,
    280    usize,
    281    Delimiter,
    282    LitKind,
    283    Level,
    284    Spacing,
    285}
    286
    287rpc_encode_decode!(
    288    enum Delimiter {
    289        Parenthesis,
    290        Brace,
    291        Bracket,
    292        None,
    293    }
    294);
    295rpc_encode_decode!(
    296    enum Level {
    297        Error,
    298        Warning,
    299        Note,
    300        Help,
    301    }
    302);
    303rpc_encode_decode!(
    304    enum Spacing {
    305        Alone,
    306        Joint,
    307    }
    308);
    309
    310#[derive(Copy, Clone, Eq, PartialEq, Debug)]
    311pub enum LitKind {
    312    Byte,
    313    Char,
    314    Integer,
    315    Float,
    316    Str,
    317    StrRaw(u8),
    318    ByteStr,
    319    ByteStrRaw(u8),
    320    CStr,
    321    CStrRaw(u8),
    322    // This should have an `ErrorGuaranteed`, except that type isn't available
    323    // in this crate. (Imagine it is there.) Hence the `WithGuar` suffix. Must
    324    // only be constructed in `LitKind::from_internal`, where an
    325    // `ErrorGuaranteed` is available.
    326    ErrWithGuar,
    327}
    328
    329rpc_encode_decode!(
    330    enum LitKind {
    331        Byte,
    332        Char,
    333        Integer,
    334        Float,
    335        Str,
    336        StrRaw(n),
    337        ByteStr,
    338        ByteStrRaw(n),
    339        CStr,
    340        CStrRaw(n),
    341        ErrWithGuar,
    342    }
    343);
    344
    345macro_rules! mark_compound {
    346    (struct $name:ident <$($T:ident),+> { $($field:ident),* $(,)? }) => {
    347        impl<$($T: Mark),+> Mark for $name <$($T),+> {
    348            type Unmarked = $name <$($T::Unmarked),+>;
    349            fn mark(unmarked: Self::Unmarked) -> Self {
    350                $name {
    351                    $($field: Mark::mark(unmarked.$field)),*
    352                }
    353            }
    354        }
    355
    356        impl<$($T: Unmark),+> Unmark for $name <$($T),+> {
    357            type Unmarked = $name <$($T::Unmarked),+>;
    358            fn unmark(self) -> Self::Unmarked {
    359                $name {
    360                    $($field: Unmark::unmark(self.$field)),*
    361                }
    362            }
    363        }
    364    };
    365    (enum $name:ident <$($T:ident),+> { $($variant:ident $(($field:ident))?),* $(,)? }) => {
    366        impl<$($T: Mark),+> Mark for $name <$($T),+> {
    367            type Unmarked = $name <$($T::Unmarked),+>;
    368            fn mark(unmarked: Self::Unmarked) -> Self {
    369                match unmarked {
    370                    $($name::$variant $(($field))? => {
    371                        $name::$variant $((Mark::mark($field)))?
    372                    })*
    373                }
    374            }
    375        }
    376
    377        impl<$($T: Unmark),+> Unmark for $name <$($T),+> {
    378            type Unmarked = $name <$($T::Unmarked),+>;
    379            fn unmark(self) -> Self::Unmarked {
    380                match self {
    381                    $($name::$variant $(($field))? => {
    382                        $name::$variant $((Unmark::unmark($field)))?
    383                    })*
    384                }
    385            }
    386        }
    387    }
    388}
    389
    390macro_rules! compound_traits {
    391    ($($t:tt)*) => {
    392        rpc_encode_decode!($($t)*);
    393        mark_compound!($($t)*);
    394    };
    395}
    396
    397compound_traits!(
    398    enum Bound<T> {
    399        Included(x),
    400        Excluded(x),
    401        Unbounded,
    402    }
    403);
    404
    405compound_traits!(
    406    enum Option<T> {
    407        Some(t),
    408        None,
    409    }
    410);
    411
    412compound_traits!(
    413    enum Result<T, E> {
    414        Ok(t),
    415        Err(e),
    416    }
    417);
    418
    419#[derive(Copy, Clone)]
    420pub struct DelimSpan<Span> {
    421    pub open: Span,
    422    pub close: Span,
    423    pub entire: Span,
    424}
    425
    426impl<Span: Copy> DelimSpan<Span> {
    427    pub fn from_single(span: Span) -> Self {
    428        DelimSpan { open: span, close: span, entire: span }
    429    }
    430}
    431
    432compound_traits!(struct DelimSpan<Span> { open, close, entire });
    433
    434#[derive(Clone)]
    435pub struct Group<TokenStream, Span> {
    436    pub delimiter: Delimiter,
    437    pub stream: Option<TokenStream>,
    438    pub span: DelimSpan<Span>,
    439}
    440
    441compound_traits!(struct Group<TokenStream, Span> { delimiter, stream, span });
    442
    443#[derive(Clone)]
    444pub struct Punct<Span> {
    445    pub ch: u8,
    446    pub joint: bool,
    447    pub span: Span,
    448}
    449
    450compound_traits!(struct Punct<Span> { ch, joint, span });
    451
    452#[derive(Copy, Clone, Eq, PartialEq)]
    453pub struct Ident<Span, Symbol> {
    454    pub sym: Symbol,
    455    pub is_raw: bool,
    456    pub span: Span,
    457}
    458
    459compound_traits!(struct Ident<Span, Symbol> { sym, is_raw, span });
    460
    461#[derive(Clone, Eq, PartialEq)]
    462pub struct Literal<Span, Symbol> {
    463    pub kind: LitKind,
    464    pub symbol: Symbol,
    465    pub suffix: Option<Symbol>,
    466    pub span: Span,
    467}
    468
    469compound_traits!(struct Literal<Sp, Sy> { kind, symbol, suffix, span });
    470
    471#[derive(Clone)]
    472pub enum TokenTree<TokenStream, Span, Symbol> {
    473    Group(Group<TokenStream, Span>),
    474    Punct(Punct<Span>),
    475    Ident(Ident<Span, Symbol>),
    476    Literal(Literal<Span, Symbol>),
    477}
    478
    479compound_traits!(
    480    enum TokenTree<TokenStream, Span, Symbol> {
    481        Group(tt),
    482        Punct(tt),
    483        Ident(tt),
    484        Literal(tt),
    485    }
    486);
    487
    488#[derive(Clone, Debug)]
    489pub struct Diagnostic<Span> {
    490    pub level: Level,
    491    pub message: String,
    492    pub spans: Vec<Span>,
    493    pub children: Vec<Diagnostic<Span>>,
    494}
    495
    496compound_traits!(
    497    struct Diagnostic<Span> { level, message, spans, children }
    498);
    499
    500/// Globals provided alongside the initial inputs for a macro expansion.
    501/// Provides values such as spans which are used frequently to avoid RPC.
    502#[derive(Clone)]
    503pub struct ExpnGlobals<Span> {
    504    pub def_site: Span,
    505    pub call_site: Span,
    506    pub mixed_site: Span,
    507}
    508
    509compound_traits!(
    510    struct ExpnGlobals<Span> { def_site, call_site, mixed_site }
    511);
    512
    513compound_traits!(
    514    struct Range<T> { start, end }
    515);