src/libcore/pin.rs

   1 //! Types which pin data to its location in memory
   2 //!
   3 //! See the [standard library module] for more information.
   4 //!
   5 //! [standard library module]: ../../std/pin/index.html
   6
   7 #![unstable(feature = "pin", issue = "49150")]
   8
   9 use fmt;
  10 use future::{Future, UnsafeFutureObj};
  11 use marker::{Sized, Unpin, Unsize};
  12 use task::{Context, Poll};
  13 use ops::{Deref, DerefMut, CoerceUnsized};
  14
  15 /// A pinned reference.
  16 ///
  17 /// This type is similar to a mutable reference, except that it pins its value,
  18 /// which prevents it from moving out of the reference, unless it implements [`Unpin`].
  19 ///
  20 /// See the [`pin` module] documentation for furthur explanation on pinning.
  21 ///
  22 /// [`Unpin`]: ../../std/marker/trait.Unpin.html
  23 /// [`pin` module]: ../../std/pin/index.html
  24 #[unstable(feature = "pin", issue = "49150")]
  25 #[fundamental]
  26 pub struct PinMut<'a, T: ?Sized + 'a> {
  27     inner: &'a mut T,
  28 }
  29
  30 #[unstable(feature = "pin", issue = "49150")]
  31 impl<'a, T: ?Sized + Unpin> PinMut<'a, T> {
  32     /// Construct a new `PinMut` around a reference to some data of a type that
  33     /// implements `Unpin`.
  34     #[unstable(feature = "pin", issue = "49150")]
  35     pub fn new(reference: &'a mut T) -> PinMut<'a, T> {
  36         PinMut { inner: reference }
  37     }
  38
  39     /// Get a mutable reference to the data inside of this `PinMut`.
  40     #[unstable(feature = "pin", issue = "49150")]
  41     pub fn get_mut(this: PinMut<'a, T>) -> &'a mut T {
  42         this.inner
  43     }
  44 }
  45
  46
  47 #[unstable(feature = "pin", issue = "49150")]
  48 impl<'a, T: ?Sized> PinMut<'a, T> {
  49     /// Construct a new `PinMut` around a reference to some data of a type that
  50     /// may or may not implement `Unpin`.
  51     ///
  52     /// This constructor is unsafe because we do not know what will happen with
  53     /// that data after the lifetime of the reference ends. If you cannot guarantee that the
  54     /// data will never move again, calling this constructor is invalid.
  55     #[unstable(feature = "pin", issue = "49150")]
  56     pub unsafe fn new_unchecked(reference: &'a mut T) -> PinMut<'a, T> {
  57         PinMut { inner: reference }
  58     }
  59
  60     /// Reborrow a `PinMut` for a shorter lifetime.
  61     ///
  62     /// For example, `PinMut::get_mut(x.reborrow())` (unsafely) returns a
  63     /// short-lived mutable reference reborrowing from `x`.
  64     #[unstable(feature = "pin", issue = "49150")]
  65     pub fn reborrow<'b>(&'b mut self) -> PinMut<'b, T> {
  66         PinMut { inner: self.inner }
  67     }
  68
  69     /// Get a mutable reference to the data inside of this `PinMut`.
  70     ///
  71     /// This function is unsafe. You must guarantee that you will never move
  72     /// the data out of the mutable reference you receive when you call this
  73     /// function.
  74     #[unstable(feature = "pin", issue = "49150")]
  75     pub unsafe fn get_mut_unchecked(this: PinMut<'a, T>) -> &'a mut T {
  76         this.inner
  77     }
  78
  79     /// Construct a new pin by mapping the interior value.
  80     ///
  81     /// For example, if you  wanted to get a `PinMut` of a field of something,
  82     /// you could use this to get access to that field in one line of code.
  83     ///
  84     /// This function is unsafe. You must guarantee that the data you return
  85     /// will not move so long as the argument value does not move (for example,
  86     /// because it is one of the fields of that value), and also that you do
  87     /// not move out of the argument you receive to the interior function.
  88     #[unstable(feature = "pin", issue = "49150")]
  89     pub unsafe fn map_unchecked<U, F>(this: PinMut<'a, T>, f: F) -> PinMut<'a, U> where
  90         F: FnOnce(&mut T) -> &mut U
  91     {
  92         PinMut { inner: f(this.inner) }
  93     }
  94
  95     /// Assign a new value to the memory behind the pinned reference.
  96     #[unstable(feature = "pin", issue = "49150")]
  97     pub fn set(this: PinMut<'a, T>, value: T)
  98         where T: Sized,
  99     {
 100         *this.inner = value;
 101     }
 102 }
 103
 104 #[unstable(feature = "pin", issue = "49150")]
 105 impl<'a, T: ?Sized> Deref for PinMut<'a, T> {
 106     type Target = T;
 107
 108     fn deref(&self) -> &T {
 109         &*self.inner
 110     }
 111 }
 112
 113 #[unstable(feature = "pin", issue = "49150")]
 114 impl<'a, T: ?Sized + Unpin> DerefMut for PinMut<'a, T> {
 115     fn deref_mut(&mut self) -> &mut T {
 116         self.inner
 117     }
 118 }
 119
 120 #[unstable(feature = "pin", issue = "49150")]
 121 impl<'a, T: fmt::Debug + ?Sized> fmt::Debug for PinMut<'a, T> {
 122     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 123         fmt::Debug::fmt(&**self, f)
 124     }
 125 }
 126
 127 #[unstable(feature = "pin", issue = "49150")]
 128 impl<'a, T: fmt::Display + ?Sized> fmt::Display for PinMut<'a, T> {
 129     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 130         fmt::Display::fmt(&**self, f)
 131     }
 132 }
 133
 134 #[unstable(feature = "pin", issue = "49150")]
 135 impl<'a, T: ?Sized> fmt::Pointer for PinMut<'a, T> {
 136     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 137         fmt::Pointer::fmt(&(&*self.inner as *const T), f)
 138     }
 139 }
 140
 141 #[unstable(feature = "pin", issue = "49150")]
 142 impl<'a, T: ?Sized + Unsize<U>, U: ?Sized> CoerceUnsized<PinMut<'a, U>> for PinMut<'a, T> {}
 143
 144 #[unstable(feature = "pin", issue = "49150")]
 145 impl<'a, T: ?Sized> Unpin for PinMut<'a, T> {}
 146
 147 #[unstable(feature = "futures_api", issue = "50547")]
 148 unsafe impl<'a, T, F> UnsafeFutureObj<'a, T> for PinMut<'a, F>
 149     where F: Future<Output = T> + 'a
 150 {
 151     fn into_raw(self) -> *mut () {
 152         unsafe { PinMut::get_mut_unchecked(self) as *mut F as *mut () }
 153     }
 154
 155     unsafe fn poll(ptr: *mut (), cx: &mut Context) -> Poll<T> {
 156         PinMut::new_unchecked(&mut *(ptr as *mut F)).poll(cx)
 157     }
 158
 159     unsafe fn drop(_ptr: *mut ()) {}
 160 }