compiler/rustc_data_structures/src/box_region.rs

   1 //! This module provides a way to deal with self-referential data.
   2 //!
   3 //! The main idea is to allocate such data in a generator frame and then
   4 //! give access to it by executing user-provided closures inside that generator.
   5 //! The module provides a safe abstraction for the latter task.
   6 //!
   7 //! The interface consists of two exported macros meant to be used together:
   8 //! * `declare_box_region_type` wraps a generator inside a struct with `access`
   9 //!   method which accepts closures.
  10 //! * `box_region_allow_access` is a helper which should be called inside
  11 //!   a generator to actually execute those closures.
  12
  13 use std::marker::PhantomData;
  14 use std::ops::{Generator, GeneratorState};
  15 use std::pin::Pin;
  16
  17 #[derive(Copy, Clone)]
  18 pub struct AccessAction(*mut dyn FnMut());
  19
  20 impl AccessAction {
  21     pub fn get(self) -> *mut dyn FnMut() {
  22         self.0
  23     }
  24 }
  25
  26 #[derive(Copy, Clone)]
  27 pub enum Action {
  28     Initial,
  29     Access(AccessAction),
  30     Complete,
  31 }
  32
  33 pub struct PinnedGenerator<I, A, R> {
  34     generator: Pin<Box<dyn Generator<Action, Yield = YieldType<I, A>, Return = R>>>,
  35 }
  36
  37 impl<I, A, R> PinnedGenerator<I, A, R> {
  38     pub fn new<T: Generator<Action, Yield = YieldType<I, A>, Return = R> + 'static>(
  39         generator: T,
  40     ) -> (I, Self) {
  41         let mut result = PinnedGenerator { generator: Box::pin(generator) };
  42
  43         // Run it to the first yield to set it up
  44         let init = match Pin::new(&mut result.generator).resume(Action::Initial) {
  45             GeneratorState::Yielded(YieldType::Initial(y)) => y,
  46             _ => panic!(),
  47         };
  48
  49         (init, result)
  50     }
  51
  52     pub unsafe fn access(&mut self, closure: *mut dyn FnMut()) {
  53         // Call the generator, which in turn will call the closure
  54         if let GeneratorState::Complete(_) =
  55             Pin::new(&mut self.generator).resume(Action::Access(AccessAction(closure)))
  56         {
  57             panic!()
  58         }
  59     }
  60
  61     pub fn complete(&mut self) -> R {
  62         // Tell the generator we want it to complete, consuming it and yielding a result
  63         let result = Pin::new(&mut self.generator).resume(Action::Complete);
  64         if let GeneratorState::Complete(r) = result { r } else { panic!() }
  65     }
  66 }
  67
  68 #[derive(PartialEq)]
  69 pub struct Marker<T>(PhantomData<T>);
  70
  71 impl<T> Marker<T> {
  72     pub unsafe fn new() -> Self {
  73         Marker(PhantomData)
  74     }
  75 }
  76
  77 pub enum YieldType<I, A> {
  78     Initial(I),
  79     Accessor(Marker<A>),
  80 }
  81
  82 #[macro_export]
  83 #[allow_internal_unstable(fn_traits)]
  84 macro_rules! declare_box_region_type {
  85     (impl $v:vis
  86      $name: ident,
  87      $yield_type:ty,
  88      for($($lifetimes:tt)*),
  89      ($($args:ty),*) -> ($reti:ty, $retc:ty)
  90     ) => {
  91         $v struct $name($crate::box_region::PinnedGenerator<
  92             $reti,
  93             for<$($lifetimes)*> fn(($($args,)*)),
  94             $retc
  95         >);
  96
  97         impl $name {
  98             fn new<T: ::std::ops::Generator<$crate::box_region::Action, Yield = $yield_type, Return = $retc> + 'static>(
  99                 generator: T
 100             ) -> ($reti, Self) {
 101                 let (initial, pinned) = $crate::box_region::PinnedGenerator::new(generator);
 102                 (initial, $name(pinned))
 103             }
 104
 105             $v fn access<F: for<$($lifetimes)*> FnOnce($($args,)*) -> R, R>(&mut self, f: F) -> R {
 106                 // Turn the FnOnce closure into *mut dyn FnMut()
 107                 // so we can pass it in to the generator
 108                 let mut r = None;
 109                 let mut f = Some(f);
 110                 let mut_f: &mut dyn for<$($lifetimes)*> FnMut(($($args,)*)) =
 111                     &mut |args| {
 112                         let f = f.take().unwrap();
 113                         r = Some(FnOnce::call_once(f, args));
 114                 };
 115                 let mut_f = mut_f as *mut dyn for<$($lifetimes)*> FnMut(($($args,)*));
 116
 117                 // Get the generator to call our closure
 118                 unsafe {
 119                     self.0.access(::std::mem::transmute(mut_f));
 120                 }
 121
 122                 // Unwrap the result
 123                 r.unwrap()
 124             }
 125
 126             $v fn complete(mut self) -> $retc {
 127                 self.0.complete()
 128             }
 129
 130             fn initial_yield(value: $reti) -> $yield_type {
 131                 $crate::box_region::YieldType::Initial(value)
 132             }
 133         }
 134     };
 135
 136     ($v:vis $name: ident, for($($lifetimes:tt)*), ($($args:ty),*) -> ($reti:ty, $retc:ty)) => {
 137         declare_box_region_type!(
 138             impl $v $name,
 139             $crate::box_region::YieldType<$reti, for<$($lifetimes)*> fn(($($args,)*))>,
 140             for($($lifetimes)*),
 141             ($($args),*) -> ($reti, $retc)
 142         );
 143     };
 144 }
 145
 146 #[macro_export]
 147 #[allow_internal_unstable(fn_traits)]
 148 macro_rules! box_region_allow_access {
 149     (for($($lifetimes:tt)*), ($($args:ty),*), ($($exprs:expr),*), $action:ident) => {
 150         loop {
 151             match $action {
 152                 $crate::box_region::Action::Access(accessor) => {
 153                     let accessor: &mut dyn for<$($lifetimes)*> FnMut($($args),*) = unsafe {
 154                         ::std::mem::transmute(accessor.get())
 155                     };
 156                     (*accessor)(($($exprs),*));
 157                     unsafe {
 158                         let marker = $crate::box_region::Marker::<
 159                             for<$($lifetimes)*> fn(($($args,)*))
 160                         >::new();
 161                         $action = yield $crate::box_region::YieldType::Accessor(marker);
 162                     };
 163                 }
 164                 $crate::box_region::Action::Complete => break,
 165                 $crate::box_region::Action::Initial => panic!("unexpected box_region action: Initial"),
 166             }
 167         }
 168     }
 169 }