src/librustc/ty/steal.rs

   1 // Copyright 2012-2015 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 use rustc_data_structures::sync::{RwLock, ReadGuard, MappedReadGuard};
  12
  13 /// The `Steal` struct is intended to used as the value for a query.
  14 /// Specifically, we sometimes have queries (*cough* MIR *cough*)
  15 /// where we create a large, complex value that we want to iteratively
  16 /// update (e.g., optimize). We could clone the value for each
  17 /// optimization, but that'd be expensive. And yet we don't just want
  18 /// to mutate it in place, because that would spoil the idea that
  19 /// queries are these pure functions that produce an immutable value
  20 /// (since if you did the query twice, you could observe the
  21 /// mutations). So instead we have the query produce a `&'tcx
  22 /// Steal<Mir<'tcx>>` (to be very specific). Now we can read from this
  23 /// as much as we want (using `borrow()`), but you can also
  24 /// `steal()`. Once you steal, any further attempt to read will panic.
  25 /// Therefore we know that -- assuming no ICE -- nobody is observing
  26 /// the fact that the MIR was updated.
  27 ///
  28 /// Obviously, whenever you have a query that yields a `Steal` value,
  29 /// you must treat it with caution, and make sure that you know that
  30 /// -- once the value is stolen -- it will never be read from again.
  31 ///
  32 /// FIXME(#41710) -- what is the best way to model linear queries?
  33 pub struct Steal<T> {
  34     value: RwLock<Option<T>>
  35 }
  36
  37 impl<T> Steal<T> {
  38     pub fn new(value: T) -> Self {
  39         Steal {
  40             value: RwLock::new(Some(value))
  41         }
  42     }
  43
  44     pub fn borrow(&self) -> MappedReadGuard<'_, T> {
  45         ReadGuard::map(self.value.borrow(), |opt| match *opt {
  46             None => bug!("attempted to read from stolen value"),
  47             Some(ref v) => v
  48         })
  49     }
  50
  51     pub fn steal(&self) -> T {
  52         let value_ref = &mut *self.value.try_write().expect("stealing value which is locked");
  53         let value = value_ref.take();
  54         value.expect("attempt to read from stolen value")
  55     }
  56 }