src/librustc_data_structures/owning_ref/mod.rs

   1 #![warn(missing_docs)]
   2
   3 /*!
   4 # An owning reference.
   5
   6 This crate provides the _owning reference_ types `OwningRef` and `OwningRefMut`
   7 that enables it to bundle a reference together with the owner of the data it points to.
   8 This allows moving and dropping of a `OwningRef` without needing to recreate the reference.
   9
  10 This can sometimes be useful because Rust borrowing rules normally prevent
  11 moving a type that has been moved from. For example, this kind of code gets rejected:
  12
  13 ```compile_fail,E0515
  14 fn return_owned_and_referenced<'a>() -> (Vec<u8>, &'a [u8]) {
  15     let v = vec![1, 2, 3, 4];
  16     let s = &v[1..3];
  17     (v, s)
  18 }
  19 ```
  20
  21 Even though, from a memory-layout point of view, this can be entirely safe
  22 if the new location of the vector still lives longer than the lifetime `'a`
  23 of the reference because the backing allocation of the vector does not change.
  24
  25 This library enables this safe usage by keeping the owner and the reference
  26 bundled together in a wrapper type that ensure that lifetime constraint:
  27
  28 ```rust
  29 # extern crate owning_ref;
  30 # use owning_ref::OwningRef;
  31 # fn main() {
  32 fn return_owned_and_referenced() -> OwningRef<Vec<u8>, [u8]> {
  33     let v = vec![1, 2, 3, 4];
  34     let or = OwningRef::new(v);
  35     let or = or.map(|v| &v[1..3]);
  36     or
  37 }
  38 # }
  39 ```
  40
  41 It works by requiring owner types to dereference to stable memory locations
  42 and preventing mutable access to root containers, which in practice requires heap allocation
  43 as provided by `Box<T>`, `Rc<T>`, etc.
  44
  45 Also provided are typedefs for common owner type combinations,
  46 which allow for less verbose type signatures.
  47 For example, `BoxRef<T>` instead of `OwningRef<Box<T>, T>`.
  48
  49 The crate also provides the more advanced `OwningHandle` type,
  50 which allows more freedom in bundling a dependent handle object
  51 along with the data it depends on, at the cost of some unsafe needed in the API.
  52 See the documentation around `OwningHandle` for more details.
  53
  54 # Examples
  55
  56 ## Basics
  57
  58 ```
  59 extern crate owning_ref;
  60 use owning_ref::BoxRef;
  61
  62 fn main() {
  63     // Create an array owned by a Box.
  64     let arr = Box::new([1, 2, 3, 4]) as Box<[i32]>;
  65
  66     // Transfer into a BoxRef.
  67     let arr: BoxRef<[i32]> = BoxRef::new(arr);
  68     assert_eq!(&*arr, &[1, 2, 3, 4]);
  69
  70     // We can slice the array without losing ownership or changing type.
  71     let arr: BoxRef<[i32]> = arr.map(|arr| &arr[1..3]);
  72     assert_eq!(&*arr, &[2, 3]);
  73
  74     // Also works for Arc, Rc, String and Vec!
  75 }
  76 ```
  77
  78 ## Caching a reference to a struct field
  79
  80 ```
  81 extern crate owning_ref;
  82 use owning_ref::BoxRef;
  83
  84 fn main() {
  85     struct Foo {
  86         tag: u32,
  87         x: u16,
  88         y: u16,
  89         z: u16,
  90     }
  91     let foo = Foo { tag: 1, x: 100, y: 200, z: 300 };
  92
  93     let or = BoxRef::new(Box::new(foo)).map(|foo| {
  94         match foo.tag {
  95             0 => &foo.x,
  96             1 => &foo.y,
  97             2 => &foo.z,
  98             _ => panic!(),
  99         }
 100     });
 101
 102     assert_eq!(*or, 200);
 103 }
 104 ```
 105
 106 ## Caching a reference to an entry in a vector
 107
 108 ```
 109 extern crate owning_ref;
 110 use owning_ref::VecRef;
 111
 112 fn main() {
 113     let v = VecRef::new(vec![1, 2, 3, 4, 5]).map(|v| &v[3]);
 114     assert_eq!(*v, 4);
 115 }
 116 ```
 117
 118 ## Caching a subslice of a String
 119
 120 ```
 121 extern crate owning_ref;
 122 use owning_ref::StringRef;
 123
 124 fn main() {
 125     let s = StringRef::new("hello world".to_owned())
 126         .map(|s| s.split(' ').nth(1).unwrap());
 127
 128     assert_eq!(&*s, "world");
 129 }
 130 ```
 131
 132 ## Reference counted slices that share ownership of the backing storage
 133
 134 ```
 135 extern crate owning_ref;
 136 use owning_ref::RcRef;
 137 use std::rc::Rc;
 138
 139 fn main() {
 140     let rc: RcRef<[i32]> = RcRef::new(Rc::new([1, 2, 3, 4]) as Rc<[i32]>);
 141     assert_eq!(&*rc, &[1, 2, 3, 4]);
 142
 143     let rc_a: RcRef<[i32]> = rc.clone().map(|s| &s[0..2]);
 144     let rc_b = rc.clone().map(|s| &s[1..3]);
 145     let rc_c = rc.clone().map(|s| &s[2..4]);
 146     assert_eq!(&*rc_a, &[1, 2]);
 147     assert_eq!(&*rc_b, &[2, 3]);
 148     assert_eq!(&*rc_c, &[3, 4]);
 149
 150     let rc_c_a = rc_c.clone().map(|s| &s[1]);
 151     assert_eq!(&*rc_c_a, &4);
 152 }
 153 ```
 154
 155 ## Atomic reference counted slices that share ownership of the backing storage
 156
 157 ```
 158 extern crate owning_ref;
 159 use owning_ref::ArcRef;
 160 use std::sync::Arc;
 161
 162 fn main() {
 163     use std::thread;
 164
 165     fn par_sum(rc: ArcRef<[i32]>) -> i32 {
 166         if rc.len() == 0 {
 167             return 0;
 168         } else if rc.len() == 1 {
 169             return rc[0];
 170         }
 171         let mid = rc.len() / 2;
 172         let left = rc.clone().map(|s| &s[..mid]);
 173         let right = rc.map(|s| &s[mid..]);
 174
 175         let left = thread::spawn(move || par_sum(left));
 176         let right = thread::spawn(move || par_sum(right));
 177
 178         left.join().unwrap() + right.join().unwrap()
 179     }
 180
 181     let rc: Arc<[i32]> = Arc::new([1, 2, 3, 4]);
 182     let rc: ArcRef<[i32]> = rc.into();
 183
 184     assert_eq!(par_sum(rc), 10);
 185 }
 186 ```
 187
 188 ## References into RAII locks
 189
 190 ```
 191 extern crate owning_ref;
 192 use owning_ref::RefRef;
 193 use std::cell::{RefCell, Ref};
 194
 195 fn main() {
 196     let refcell = RefCell::new((1, 2, 3, 4));
 197     // Also works with Mutex and RwLock
 198
 199     let refref = {
 200         let refref = RefRef::new(refcell.borrow()).map(|x| &x.3);
 201         assert_eq!(*refref, 4);
 202
 203         // We move the RAII lock and the reference to one of
 204         // the subfields in the data it guards here:
 205         refref
 206     };
 207
 208     assert_eq!(*refref, 4);
 209
 210     drop(refref);
 211
 212     assert_eq!(*refcell.borrow(), (1, 2, 3, 4));
 213 }
 214 ```
 215
 216 ## Mutable reference
 217
 218 When the owned container implements `DerefMut`, it is also possible to make
 219 a _mutable owning reference_. (e.g., with `Box`, `RefMut`, `MutexGuard`)
 220
 221 ```
 222 extern crate owning_ref;
 223 use owning_ref::RefMutRefMut;
 224 use std::cell::{RefCell, RefMut};
 225
 226 fn main() {
 227     let refcell = RefCell::new((1, 2, 3, 4));
 228
 229     let mut refmut_refmut = {
 230         let mut refmut_refmut = RefMutRefMut::new(refcell.borrow_mut()).map_mut(|x| &mut x.3);
 231         assert_eq!(*refmut_refmut, 4);
 232         *refmut_refmut *= 2;
 233
 234         refmut_refmut
 235     };
 236
 237     assert_eq!(*refmut_refmut, 8);
 238     *refmut_refmut *= 2;
 239
 240     drop(refmut_refmut);
 241
 242     assert_eq!(*refcell.borrow(), (1, 2, 3, 16));
 243 }
 244 ```
 245 */
 246
 247 use std::mem;
 248 pub use stable_deref_trait::{StableDeref as StableAddress, CloneStableDeref as CloneStableAddress};
 249
 250 /// An owning reference.
 251 ///
 252 /// This wraps an owner `O` and a reference `&T` pointing
 253 /// at something reachable from `O::Target` while keeping
 254 /// the ability to move `self` around.
 255 ///
 256 /// The owner is usually a pointer that points at some base type.
 257 ///
 258 /// For more details and examples, see the module and method docs.
 259 pub struct OwningRef<O, T: ?Sized> {
 260     owner: O,
 261     reference: *const T,
 262 }
 263
 264 /// An mutable owning reference.
 265 ///
 266 /// This wraps an owner `O` and a reference `&mut T` pointing
 267 /// at something reachable from `O::Target` while keeping
 268 /// the ability to move `self` around.
 269 ///
 270 /// The owner is usually a pointer that points at some base type.
 271 ///
 272 /// For more details and examples, see the module and method docs.
 273 pub struct OwningRefMut<O, T: ?Sized> {
 274     owner: O,
 275     reference: *mut T,
 276 }
 277
 278 /// Helper trait for an erased concrete type an owner dereferences to.
 279 /// This is used in form of a trait object for keeping
 280 /// something around to (virtually) call the destructor.
 281 pub trait Erased {}
 282 impl<T> Erased for T {}
 283
 284 /// Helper trait for erasing the concrete type of what an owner dereferences to,
 285 /// for example `Box<T> -> Box<Erased>`. This would be unneeded with
 286 /// higher kinded types support in the language.
 287 #[allow(unused_lifetimes)]
 288 pub unsafe trait IntoErased<'a> {
 289     /// Owner with the dereference type substituted to `Erased`.
 290     type Erased;
 291     /// Performs the type erasure.
 292     fn into_erased(self) -> Self::Erased;
 293 }
 294
 295 /// Helper trait for erasing the concrete type of what an owner dereferences to,
 296 /// for example `Box<T> -> Box<Erased + Send>`. This would be unneeded with
 297 /// higher kinded types support in the language.
 298 #[allow(unused_lifetimes)]
 299 pub unsafe trait IntoErasedSend<'a> {
 300     /// Owner with the dereference type substituted to `Erased + Send`.
 301     type Erased: Send;
 302     /// Performs the type erasure.
 303     fn into_erased_send(self) -> Self::Erased;
 304 }
 305
 306 /// Helper trait for erasing the concrete type of what an owner dereferences to,
 307 /// for example `Box<T> -> Box<Erased + Send + Sync>`. This would be unneeded with
 308 /// higher kinded types support in the language.
 309 #[allow(unused_lifetimes)]
 310 pub unsafe trait IntoErasedSendSync<'a> {
 311     /// Owner with the dereference type substituted to `Erased + Send + Sync`.
 312     type Erased: Send + Sync;
 313     /// Performs the type erasure.
 314     fn into_erased_send_sync(self) -> Self::Erased;
 315 }
 316
 317 /////////////////////////////////////////////////////////////////////////////
 318 // OwningRef
 319 /////////////////////////////////////////////////////////////////////////////
 320
 321 impl<O, T: ?Sized> OwningRef<O, T> {
 322     /// Creates a new owning reference from a owner
 323     /// initialized to the direct dereference of it.
 324     ///
 325     /// # Example
 326     /// ```
 327     /// extern crate owning_ref;
 328     /// use owning_ref::OwningRef;
 329     ///
 330     /// fn main() {
 331     ///     let owning_ref = OwningRef::new(Box::new(42));
 332     ///     assert_eq!(*owning_ref, 42);
 333     /// }
 334     /// ```
 335     pub fn new(o: O) -> Self
 336         where O: StableAddress,
 337               O: Deref<Target = T>,
 338     {
 339         OwningRef {
 340             reference: &*o,
 341             owner: o,
 342         }
 343     }
 344
 345     /// Like `new`, but doesn’t require `O` to implement the `StableAddress` trait.
 346     /// Instead, the caller is responsible to make the same promises as implementing the trait.
 347     ///
 348     /// This is useful for cases where coherence rules prevents implementing the trait
 349     /// without adding a dependency to this crate in a third-party library.
 350     pub unsafe fn new_assert_stable_address(o: O) -> Self
 351         where O: Deref<Target = T>,
 352     {
 353         OwningRef {
 354             reference: &*o,
 355             owner: o,
 356         }
 357     }
 358
 359     /// Converts `self` into a new owning reference that points at something reachable
 360     /// from the previous one.
 361     ///
 362     /// This can be a reference to a field of `U`, something reachable from a field of
 363     /// `U`, or even something unrelated with a `'static` lifetime.
 364     ///
 365     /// # Example
 366     /// ```
 367     /// extern crate owning_ref;
 368     /// use owning_ref::OwningRef;
 369     ///
 370     /// fn main() {
 371     ///     let owning_ref = OwningRef::new(Box::new([1, 2, 3, 4]));
 372     ///
 373     ///     // create a owning reference that points at the
 374     ///     // third element of the array.
 375     ///     let owning_ref = owning_ref.map(|array| &array[2]);
 376     ///     assert_eq!(*owning_ref, 3);
 377     /// }
 378     /// ```
 379     pub fn map<F, U: ?Sized>(self, f: F) -> OwningRef<O, U>
 380         where O: StableAddress,
 381               F: FnOnce(&T) -> &U
 382     {
 383         OwningRef {
 384             reference: f(&self),
 385             owner: self.owner,
 386         }
 387     }
 388
 389     /// Tries to convert `self` into a new owning reference that points
 390     /// at something reachable from the previous one.
 391     ///
 392     /// This can be a reference to a field of `U`, something reachable from a field of
 393     /// `U`, or even something unrelated with a `'static` lifetime.
 394     ///
 395     /// # Example
 396     /// ```
 397     /// extern crate owning_ref;
 398     /// use owning_ref::OwningRef;
 399     ///
 400     /// fn main() {
 401     ///     let owning_ref = OwningRef::new(Box::new([1, 2, 3, 4]));
 402     ///
 403     ///     // create a owning reference that points at the
 404     ///     // third element of the array.
 405     ///     let owning_ref = owning_ref.try_map(|array| {
 406     ///         if array[2] == 3 { Ok(&array[2]) } else { Err(()) }
 407     ///     });
 408     ///     assert_eq!(*owning_ref.unwrap(), 3);
 409     /// }
 410     /// ```
 411     pub fn try_map<F, U: ?Sized, E>(self, f: F) -> Result<OwningRef<O, U>, E>
 412         where O: StableAddress,
 413               F: FnOnce(&T) -> Result<&U, E>
 414     {
 415         Ok(OwningRef {
 416             reference: f(&self)?,
 417             owner: self.owner,
 418         })
 419     }
 420
 421     /// Converts `self` into a new owning reference with a different owner type.
 422     ///
 423     /// The new owner type needs to still contain the original owner in some way
 424     /// so that the reference into it remains valid. This function is marked unsafe
 425     /// because the user needs to manually uphold this guarantee.
 426     pub unsafe fn map_owner<F, P>(self, f: F) -> OwningRef<P, T>
 427         where O: StableAddress,
 428               P: StableAddress,
 429               F: FnOnce(O) -> P
 430     {
 431         OwningRef {
 432             reference: self.reference,
 433             owner: f(self.owner),
 434         }
 435     }
 436
 437     /// Converts `self` into a new owning reference where the owner is wrapped
 438     /// in an additional `Box<O>`.
 439     ///
 440     /// This can be used to safely erase the owner of any `OwningRef<O, T>`
 441     /// to a `OwningRef<Box<Erased>, T>`.
 442     pub fn map_owner_box(self) -> OwningRef<Box<O>, T> {
 443         OwningRef {
 444             reference: self.reference,
 445             owner: Box::new(self.owner),
 446         }
 447     }
 448
 449     /// Erases the concrete base type of the owner with a trait object.
 450     ///
 451     /// This allows mixing of owned references with different owner base types.
 452     ///
 453     /// # Example
 454     /// ```
 455     /// extern crate owning_ref;
 456     /// use owning_ref::{OwningRef, Erased};
 457     ///
 458     /// fn main() {
 459     ///     // N.B., using the concrete types here for explicitness.
 460     ///     // For less verbose code type aliases like `BoxRef` are provided.
 461     ///
 462     ///     let owning_ref_a: OwningRef<Box<[i32; 4]>, [i32; 4]>
 463     ///         = OwningRef::new(Box::new([1, 2, 3, 4]));
 464     ///
 465     ///     let owning_ref_b: OwningRef<Box<Vec<(i32, bool)>>, Vec<(i32, bool)>>
 466     ///         = OwningRef::new(Box::new(vec![(0, false), (1, true)]));
 467     ///
 468     ///     let owning_ref_a: OwningRef<Box<[i32; 4]>, i32>
 469     ///         = owning_ref_a.map(|a| &a[0]);
 470     ///
 471     ///     let owning_ref_b: OwningRef<Box<Vec<(i32, bool)>>, i32>
 472     ///         = owning_ref_b.map(|a| &a[1].0);
 473     ///
 474     ///     let owning_refs: [OwningRef<Box<Erased>, i32>; 2]
 475     ///         = [owning_ref_a.erase_owner(), owning_ref_b.erase_owner()];
 476     ///
 477     ///     assert_eq!(*owning_refs[0], 1);
 478     ///     assert_eq!(*owning_refs[1], 1);
 479     /// }
 480     /// ```
 481     pub fn erase_owner<'a>(self) -> OwningRef<O::Erased, T>
 482         where O: IntoErased<'a>,
 483     {
 484         OwningRef {
 485             reference: self.reference,
 486             owner: self.owner.into_erased(),
 487         }
 488     }
 489
 490     /// Erases the concrete base type of the owner with a trait object which implements `Send`.
 491     ///
 492     /// This allows mixing of owned references with different owner base types.
 493     pub fn erase_send_owner<'a>(self) -> OwningRef<O::Erased, T>
 494         where O: IntoErasedSend<'a>,
 495     {
 496         OwningRef {
 497             reference: self.reference,
 498             owner: self.owner.into_erased_send(),
 499         }
 500     }
 501
 502     /// Erases the concrete base type of the owner with a trait object
 503     /// which implements `Send` and `Sync`.
 504     ///
 505     /// This allows mixing of owned references with different owner base types.
 506     pub fn erase_send_sync_owner<'a>(self) -> OwningRef<O::Erased, T>
 507         where O: IntoErasedSendSync<'a>,
 508     {
 509         OwningRef {
 510             reference: self.reference,
 511             owner: self.owner.into_erased_send_sync(),
 512         }
 513     }
 514
 515     // UNIMPLEMENTED: wrap_owner
 516
 517     // FIXME: Naming convention?
 518     /// A getter for the underlying owner.
 519     pub fn owner(&self) -> &O {
 520         &self.owner
 521     }
 522
 523     // FIXME: Naming convention?
 524     /// Discards the reference and retrieves the owner.
 525     pub fn into_inner(self) -> O {
 526         self.owner
 527     }
 528 }
 529
 530 impl<O, T: ?Sized> OwningRefMut<O, T> {
 531     /// Creates a new owning reference from a owner
 532     /// initialized to the direct dereference of it.
 533     ///
 534     /// # Example
 535     /// ```
 536     /// extern crate owning_ref;
 537     /// use owning_ref::OwningRefMut;
 538     ///
 539     /// fn main() {
 540     ///     let owning_ref_mut = OwningRefMut::new(Box::new(42));
 541     ///     assert_eq!(*owning_ref_mut, 42);
 542     /// }
 543     /// ```
 544     pub fn new(mut o: O) -> Self
 545         where O: StableAddress,
 546               O: DerefMut<Target = T>,
 547     {
 548         OwningRefMut {
 549             reference: &mut *o,
 550             owner: o,
 551         }
 552     }
 553
 554     /// Like `new`, but doesn’t require `O` to implement the `StableAddress` trait.
 555     /// Instead, the caller is responsible to make the same promises as implementing the trait.
 556     ///
 557     /// This is useful for cases where coherence rules prevents implementing the trait
 558     /// without adding a dependency to this crate in a third-party library.
 559     pub unsafe fn new_assert_stable_address(mut o: O) -> Self
 560         where O: DerefMut<Target = T>,
 561     {
 562         OwningRefMut {
 563             reference: &mut *o,
 564             owner: o,
 565         }
 566     }
 567
 568     /// Converts `self` into a new _shared_ owning reference that points at
 569     /// something reachable from the previous one.
 570     ///
 571     /// This can be a reference to a field of `U`, something reachable from a field of
 572     /// `U`, or even something unrelated with a `'static` lifetime.
 573     ///
 574     /// # Example
 575     /// ```
 576     /// extern crate owning_ref;
 577     /// use owning_ref::OwningRefMut;
 578     ///
 579     /// fn main() {
 580     ///     let owning_ref_mut = OwningRefMut::new(Box::new([1, 2, 3, 4]));
 581     ///
 582     ///     // create a owning reference that points at the
 583     ///     // third element of the array.
 584     ///     let owning_ref = owning_ref_mut.map(|array| &array[2]);
 585     ///     assert_eq!(*owning_ref, 3);
 586     /// }
 587     /// ```
 588     pub fn map<F, U: ?Sized>(mut self, f: F) -> OwningRef<O, U>
 589         where O: StableAddress,
 590               F: FnOnce(&mut T) -> &U
 591     {
 592         OwningRef {
 593             reference: f(&mut self),
 594             owner: self.owner,
 595         }
 596     }
 597
 598     /// Converts `self` into a new _mutable_ owning reference that points at
 599     /// something reachable from the previous one.
 600     ///
 601     /// This can be a reference to a field of `U`, something reachable from a field of
 602     /// `U`, or even something unrelated with a `'static` lifetime.
 603     ///
 604     /// # Example
 605     /// ```
 606     /// extern crate owning_ref;
 607     /// use owning_ref::OwningRefMut;
 608     ///
 609     /// fn main() {
 610     ///     let owning_ref_mut = OwningRefMut::new(Box::new([1, 2, 3, 4]));
 611     ///
 612     ///     // create a owning reference that points at the
 613     ///     // third element of the array.
 614     ///     let owning_ref_mut = owning_ref_mut.map_mut(|array| &mut array[2]);
 615     ///     assert_eq!(*owning_ref_mut, 3);
 616     /// }
 617     /// ```
 618     pub fn map_mut<F, U: ?Sized>(mut self, f: F) -> OwningRefMut<O, U>
 619         where O: StableAddress,
 620               F: FnOnce(&mut T) -> &mut U
 621     {
 622         OwningRefMut {
 623             reference: f(&mut self),
 624             owner: self.owner,
 625         }
 626     }
 627
 628     /// Tries to convert `self` into a new _shared_ owning reference that points
 629     /// at something reachable from the previous one.
 630     ///
 631     /// This can be a reference to a field of `U`, something reachable from a field of
 632     /// `U`, or even something unrelated with a `'static` lifetime.
 633     ///
 634     /// # Example
 635     /// ```
 636     /// extern crate owning_ref;
 637     /// use owning_ref::OwningRefMut;
 638     ///
 639     /// fn main() {
 640     ///     let owning_ref_mut = OwningRefMut::new(Box::new([1, 2, 3, 4]));
 641     ///
 642     ///     // create a owning reference that points at the
 643     ///     // third element of the array.
 644     ///     let owning_ref = owning_ref_mut.try_map(|array| {
 645     ///         if array[2] == 3 { Ok(&array[2]) } else { Err(()) }
 646     ///     });
 647     ///     assert_eq!(*owning_ref.unwrap(), 3);
 648     /// }
 649     /// ```
 650     pub fn try_map<F, U: ?Sized, E>(mut self, f: F) -> Result<OwningRef<O, U>, E>
 651         where O: StableAddress,
 652               F: FnOnce(&mut T) -> Result<&U, E>
 653     {
 654         Ok(OwningRef {
 655             reference: f(&mut self)?,
 656             owner: self.owner,
 657         })
 658     }
 659
 660     /// Tries to convert `self` into a new _mutable_ owning reference that points
 661     /// at something reachable from the previous one.
 662     ///
 663     /// This can be a reference to a field of `U`, something reachable from a field of
 664     /// `U`, or even something unrelated with a `'static` lifetime.
 665     ///
 666     /// # Example
 667     /// ```
 668     /// extern crate owning_ref;
 669     /// use owning_ref::OwningRefMut;
 670     ///
 671     /// fn main() {
 672     ///     let owning_ref_mut = OwningRefMut::new(Box::new([1, 2, 3, 4]));
 673     ///
 674     ///     // create a owning reference that points at the
 675     ///     // third element of the array.
 676     ///     let owning_ref_mut = owning_ref_mut.try_map_mut(|array| {
 677     ///         if array[2] == 3 { Ok(&mut array[2]) } else { Err(()) }
 678     ///     });
 679     ///     assert_eq!(*owning_ref_mut.unwrap(), 3);
 680     /// }
 681     /// ```
 682     pub fn try_map_mut<F, U: ?Sized, E>(mut self, f: F) -> Result<OwningRefMut<O, U>, E>
 683         where O: StableAddress,
 684               F: FnOnce(&mut T) -> Result<&mut U, E>
 685     {
 686         Ok(OwningRefMut {
 687             reference: f(&mut self)?,
 688             owner: self.owner,
 689         })
 690     }
 691
 692     /// Converts `self` into a new owning reference with a different owner type.
 693     ///
 694     /// The new owner type needs to still contain the original owner in some way
 695     /// so that the reference into it remains valid. This function is marked unsafe
 696     /// because the user needs to manually uphold this guarantee.
 697     pub unsafe fn map_owner<F, P>(self, f: F) -> OwningRefMut<P, T>
 698         where O: StableAddress,
 699               P: StableAddress,
 700               F: FnOnce(O) -> P
 701     {
 702         OwningRefMut {
 703             reference: self.reference,
 704             owner: f(self.owner),
 705         }
 706     }
 707
 708     /// Converts `self` into a new owning reference where the owner is wrapped
 709     /// in an additional `Box<O>`.
 710     ///
 711     /// This can be used to safely erase the owner of any `OwningRefMut<O, T>`
 712     /// to a `OwningRefMut<Box<Erased>, T>`.
 713     pub fn map_owner_box(self) -> OwningRefMut<Box<O>, T> {
 714         OwningRefMut {
 715             reference: self.reference,
 716             owner: Box::new(self.owner),
 717         }
 718     }
 719
 720     /// Erases the concrete base type of the owner with a trait object.
 721     ///
 722     /// This allows mixing of owned references with different owner base types.
 723     ///
 724     /// # Example
 725     /// ```
 726     /// extern crate owning_ref;
 727     /// use owning_ref::{OwningRefMut, Erased};
 728     ///
 729     /// fn main() {
 730     ///     // N.B., using the concrete types here for explicitness.
 731     ///     // For less verbose code type aliases like `BoxRef` are provided.
 732     ///
 733     ///     let owning_ref_mut_a: OwningRefMut<Box<[i32; 4]>, [i32; 4]>
 734     ///         = OwningRefMut::new(Box::new([1, 2, 3, 4]));
 735     ///
 736     ///     let owning_ref_mut_b: OwningRefMut<Box<Vec<(i32, bool)>>, Vec<(i32, bool)>>
 737     ///         = OwningRefMut::new(Box::new(vec![(0, false), (1, true)]));
 738     ///
 739     ///     let owning_ref_mut_a: OwningRefMut<Box<[i32; 4]>, i32>
 740     ///         = owning_ref_mut_a.map_mut(|a| &mut a[0]);
 741     ///
 742     ///     let owning_ref_mut_b: OwningRefMut<Box<Vec<(i32, bool)>>, i32>
 743     ///         = owning_ref_mut_b.map_mut(|a| &mut a[1].0);
 744     ///
 745     ///     let owning_refs_mut: [OwningRefMut<Box<Erased>, i32>; 2]
 746     ///         = [owning_ref_mut_a.erase_owner(), owning_ref_mut_b.erase_owner()];
 747     ///
 748     ///     assert_eq!(*owning_refs_mut[0], 1);
 749     ///     assert_eq!(*owning_refs_mut[1], 1);
 750     /// }
 751     /// ```
 752     pub fn erase_owner<'a>(self) -> OwningRefMut<O::Erased, T>
 753         where O: IntoErased<'a>,
 754     {
 755         OwningRefMut {
 756             reference: self.reference,
 757             owner: self.owner.into_erased(),
 758         }
 759     }
 760
 761     // UNIMPLEMENTED: wrap_owner
 762
 763     // FIXME: Naming convention?
 764     /// A getter for the underlying owner.
 765     pub fn owner(&self) -> &O {
 766         &self.owner
 767     }
 768
 769     // FIXME: Naming convention?
 770     /// Discards the reference and retrieves the owner.
 771     pub fn into_inner(self) -> O {
 772         self.owner
 773     }
 774 }
 775
 776 /////////////////////////////////////////////////////////////////////////////
 777 // OwningHandle
 778 /////////////////////////////////////////////////////////////////////////////
 779
 780 use std::ops::{Deref, DerefMut};
 781
 782 /// `OwningHandle` is a complement to `OwningRef`. Where `OwningRef` allows
 783 /// consumers to pass around an owned object and a dependent reference,
 784 /// `OwningHandle` contains an owned object and a dependent _object_.
 785 ///
 786 /// `OwningHandle` can encapsulate a `RefMut` along with its associated
 787 /// `RefCell`, or an `RwLockReadGuard` along with its associated `RwLock`.
 788 /// However, the API is completely generic and there are no restrictions on
 789 /// what types of owning and dependent objects may be used.
 790 ///
 791 /// `OwningHandle` is created by passing an owner object (which dereferences
 792 /// to a stable address) along with a callback which receives a pointer to
 793 /// that stable location. The callback may then dereference the pointer and
 794 /// mint a dependent object, with the guarantee that the returned object will
 795 /// not outlive the referent of the pointer.
 796 ///
 797 /// Since the callback needs to dereference a raw pointer, it requires `unsafe`
 798 /// code. To avoid forcing this unsafety on most callers, the `ToHandle` trait is
 799 /// implemented for common data structures. Types that implement `ToHandle` can
 800 /// be wrapped into an `OwningHandle` without passing a callback.
 801 pub struct OwningHandle<O, H>
 802     where O: StableAddress, H: Deref,
 803 {
 804     handle: H,
 805     _owner: O,
 806 }
 807
 808 impl<O, H> Deref for OwningHandle<O, H>
 809     where O: StableAddress, H: Deref,
 810 {
 811     type Target = H::Target;
 812     fn deref(&self) -> &H::Target {
 813         self.handle.deref()
 814     }
 815 }
 816
 817 unsafe impl<O, H> StableAddress for OwningHandle<O, H>
 818     where O: StableAddress, H: StableAddress,
 819 {}
 820
 821 impl<O, H> DerefMut for OwningHandle<O, H>
 822     where O: StableAddress, H: DerefMut,
 823 {
 824     fn deref_mut(&mut self) -> &mut H::Target {
 825         self.handle.deref_mut()
 826     }
 827 }
 828
 829 /// Trait to implement the conversion of owner to handle for common types.
 830 pub trait ToHandle {
 831     /// The type of handle to be encapsulated by the OwningHandle.
 832     type Handle: Deref;
 833
 834     /// Given an appropriately-long-lived pointer to ourselves, create a
 835     /// handle to be encapsulated by the `OwningHandle`.
 836     unsafe fn to_handle(x: *const Self) -> Self::Handle;
 837 }
 838
 839 /// Trait to implement the conversion of owner to mutable handle for common types.
 840 pub trait ToHandleMut {
 841     /// The type of handle to be encapsulated by the OwningHandle.
 842     type HandleMut: DerefMut;
 843
 844     /// Given an appropriately-long-lived pointer to ourselves, create a
 845     /// mutable handle to be encapsulated by the `OwningHandle`.
 846     unsafe fn to_handle_mut(x: *const Self) -> Self::HandleMut;
 847 }
 848
 849 impl<O, H> OwningHandle<O, H>
 850     where O: StableAddress, O::Target: ToHandle<Handle = H>, H: Deref,
 851 {
 852     /// Creates a new `OwningHandle` for a type that implements `ToHandle`. For types
 853     /// that don't implement `ToHandle`, callers may invoke `new_with_fn`, which accepts
 854     /// a callback to perform the conversion.
 855     pub fn new(o: O) -> Self {
 856         OwningHandle::new_with_fn(o, |x| unsafe { O::Target::to_handle(x) })
 857     }
 858 }
 859
 860 impl<O, H> OwningHandle<O, H>
 861     where O: StableAddress, O::Target: ToHandleMut<HandleMut = H>, H: DerefMut,
 862 {
 863     /// Creates a new mutable `OwningHandle` for a type that implements `ToHandleMut`.
 864     pub fn new_mut(o: O) -> Self {
 865         OwningHandle::new_with_fn(o, |x| unsafe { O::Target::to_handle_mut(x) })
 866     }
 867 }
 868
 869 impl<O, H> OwningHandle<O, H>
 870     where O: StableAddress, H: Deref,
 871 {
 872     /// Creates a new OwningHandle. The provided callback will be invoked with
 873     /// a pointer to the object owned by `o`, and the returned value is stored
 874     /// as the object to which this `OwningHandle` will forward `Deref` and
 875     /// `DerefMut`.
 876     pub fn new_with_fn<F>(o: O, f: F) -> Self
 877         where F: FnOnce(*const O::Target) -> H
 878     {
 879         let h: H;
 880         {
 881             h = f(o.deref() as *const O::Target);
 882         }
 883
 884         OwningHandle {
 885           handle: h,
 886           _owner: o,
 887         }
 888     }
 889
 890     /// Creates a new OwningHandle. The provided callback will be invoked with
 891     /// a pointer to the object owned by `o`, and the returned value is stored
 892     /// as the object to which this `OwningHandle` will forward `Deref` and
 893     /// `DerefMut`.
 894     pub fn try_new<F, E>(o: O, f: F) -> Result<Self, E>
 895         where F: FnOnce(*const O::Target) -> Result<H, E>
 896     {
 897         let h: H;
 898         {
 899             h = f(o.deref() as *const O::Target)?;
 900         }
 901
 902         Ok(OwningHandle {
 903           handle: h,
 904           _owner: o,
 905         })
 906     }
 907 }
 908
 909 /////////////////////////////////////////////////////////////////////////////
 910 // std traits
 911 /////////////////////////////////////////////////////////////////////////////
 912
 913 use std::convert::From;
 914 use std::fmt::{self, Debug};
 915 use std::marker::{Send, Sync};
 916 use std::cmp::{Eq, PartialEq, Ord, PartialOrd, Ordering};
 917 use std::hash::{Hash, Hasher};
 918 use std::borrow::Borrow;
 919
 920 impl<O, T: ?Sized> Deref for OwningRef<O, T> {
 921     type Target = T;
 922
 923     fn deref(&self) -> &T {
 924         unsafe {
 925             &*self.reference
 926         }
 927     }
 928 }
 929
 930 impl<O, T: ?Sized> Deref for OwningRefMut<O, T> {
 931     type Target = T;
 932
 933     fn deref(&self) -> &T {
 934         unsafe {
 935             &*self.reference
 936         }
 937     }
 938 }
 939
 940 impl<O, T: ?Sized> DerefMut for OwningRefMut<O, T> {
 941     fn deref_mut(&mut self) -> &mut T {
 942         unsafe {
 943             &mut *self.reference
 944         }
 945     }
 946 }
 947
 948 unsafe impl<O, T: ?Sized> StableAddress for OwningRef<O, T> {}
 949
 950 impl<O, T: ?Sized> AsRef<T> for OwningRef<O, T> {
 951     fn as_ref(&self) -> &T {
 952         &*self
 953     }
 954 }
 955
 956 impl<O, T: ?Sized> AsRef<T> for OwningRefMut<O, T> {
 957     fn as_ref(&self) -> &T {
 958         &*self
 959     }
 960 }
 961
 962 impl<O, T: ?Sized> AsMut<T> for OwningRefMut<O, T> {
 963     fn as_mut(&mut self) -> &mut T {
 964         &mut *self
 965     }
 966 }
 967
 968 impl<O, T: ?Sized> Borrow<T> for OwningRef<O, T> {
 969     fn borrow(&self) -> &T {
 970         &*self
 971     }
 972 }
 973
 974 impl<O, T: ?Sized> From<O> for OwningRef<O, T>
 975     where O: StableAddress,
 976           O: Deref<Target = T>,
 977 {
 978     fn from(owner: O) -> Self {
 979         OwningRef::new(owner)
 980     }
 981 }
 982
 983 impl<O, T: ?Sized> From<O> for OwningRefMut<O, T>
 984     where O: StableAddress,
 985           O: DerefMut<Target = T>
 986 {
 987     fn from(owner: O) -> Self {
 988         OwningRefMut::new(owner)
 989     }
 990 }
 991
 992 impl<O, T: ?Sized> From<OwningRefMut<O, T>> for OwningRef<O, T>
 993     where O: StableAddress,
 994           O: DerefMut<Target = T>
 995 {
 996     fn from(other: OwningRefMut<O, T>) -> Self {
 997         OwningRef {
 998             owner: other.owner,
 999             reference: other.reference,
1000         }
1001     }
1002 }
1003
1004 // ^ FIXME: Is a Into impl for calling into_inner() possible as well?
1005
1006 impl<O, T: ?Sized> Debug for OwningRef<O, T>
1007     where O: Debug,
1008           T: Debug,
1009 {
1010     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1011         write!(f,
1012                "OwningRef {{ owner: {:?}, reference: {:?} }}",
1013                self.owner(),
1014                &**self)
1015     }
1016 }
1017
1018 impl<O, T: ?Sized> Debug for OwningRefMut<O, T>
1019     where O: Debug,
1020           T: Debug,
1021 {
1022     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1023         write!(f,
1024                "OwningRefMut {{ owner: {:?}, reference: {:?} }}",
1025                self.owner(),
1026                &**self)
1027     }
1028 }
1029
1030 impl<O, T: ?Sized> Clone for OwningRef<O, T>
1031     where O: CloneStableAddress,
1032 {
1033     fn clone(&self) -> Self {
1034         OwningRef {
1035             owner: self.owner.clone(),
1036             reference: self.reference,
1037         }
1038     }
1039 }
1040
1041 unsafe impl<O, T: ?Sized> CloneStableAddress for OwningRef<O, T>
1042     where O: CloneStableAddress {}
1043
1044 unsafe impl<O, T: ?Sized> Send for OwningRef<O, T>
1045     where O: Send, for<'a> (&'a T): Send {}
1046 unsafe impl<O, T: ?Sized> Sync for OwningRef<O, T>
1047     where O: Sync, for<'a> (&'a T): Sync {}
1048
1049 unsafe impl<O, T: ?Sized> Send for OwningRefMut<O, T>
1050     where O: Send, for<'a> (&'a mut T): Send {}
1051 unsafe impl<O, T: ?Sized> Sync for OwningRefMut<O, T>
1052     where O: Sync, for<'a> (&'a mut T): Sync {}
1053
1054 impl Debug for dyn Erased {
1055     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1056         write!(f, "<Erased>",)
1057     }
1058 }
1059
1060 impl<O, T: ?Sized> PartialEq for OwningRef<O, T> where T: PartialEq {
1061     fn eq(&self, other: &Self) -> bool {
1062         (&*self as &T).eq(&*other as &T)
1063      }
1064 }
1065
1066 impl<O, T: ?Sized> Eq for OwningRef<O, T> where T: Eq {}
1067
1068 impl<O, T: ?Sized> PartialOrd for OwningRef<O, T> where T: PartialOrd {
1069     fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
1070         (&*self as &T).partial_cmp(&*other as &T)
1071     }
1072 }
1073
1074 impl<O, T: ?Sized> Ord for OwningRef<O, T> where T: Ord {
1075     fn cmp(&self, other: &Self) -> Ordering {
1076         (&*self as &T).cmp(&*other as &T)
1077     }
1078 }
1079
1080 impl<O, T: ?Sized> Hash for OwningRef<O, T> where T: Hash {
1081     fn hash<H: Hasher>(&self, state: &mut H) {
1082         (&*self as &T).hash(state);
1083     }
1084 }
1085
1086 impl<O, T: ?Sized> PartialEq for OwningRefMut<O, T> where T: PartialEq {
1087     fn eq(&self, other: &Self) -> bool {
1088         (&*self as &T).eq(&*other as &T)
1089      }
1090 }
1091
1092 impl<O, T: ?Sized> Eq for OwningRefMut<O, T> where T: Eq {}
1093
1094 impl<O, T: ?Sized> PartialOrd for OwningRefMut<O, T> where T: PartialOrd {
1095     fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
1096         (&*self as &T).partial_cmp(&*other as &T)
1097     }
1098 }
1099
1100 impl<O, T: ?Sized> Ord for OwningRefMut<O, T> where T: Ord {
1101     fn cmp(&self, other: &Self) -> Ordering {
1102         (&*self as &T).cmp(&*other as &T)
1103     }
1104 }
1105
1106 impl<O, T: ?Sized> Hash for OwningRefMut<O, T> where T: Hash {
1107     fn hash<H: Hasher>(&self, state: &mut H) {
1108         (&*self as &T).hash(state);
1109     }
1110 }
1111
1112 /////////////////////////////////////////////////////////////////////////////
1113 // std types integration and convenience type defs
1114 /////////////////////////////////////////////////////////////////////////////
1115
1116 use std::boxed::Box;
1117 use std::rc::Rc;
1118 use std::sync::Arc;
1119 use std::sync::{MutexGuard, RwLockReadGuard, RwLockWriteGuard};
1120 use std::cell::{Ref, RefCell, RefMut};
1121
1122 impl<T: 'static> ToHandle for RefCell<T> {
1123     type Handle = Ref<'static, T>;
1124     unsafe fn to_handle(x: *const Self) -> Self::Handle { (*x).borrow() }
1125 }
1126
1127 impl<T: 'static> ToHandleMut for RefCell<T> {
1128     type HandleMut = RefMut<'static, T>;
1129     unsafe fn to_handle_mut(x: *const Self) -> Self::HandleMut { (*x).borrow_mut() }
1130 }
1131
1132 // N.B., implementing ToHandle{,Mut} for Mutex and RwLock requires a decision
1133 // about which handle creation to use (i.e., read() vs try_read()) as well as
1134 // what to do with error results.
1135
1136 /// Typedef of a owning reference that uses a `Box` as the owner.
1137 pub type BoxRef<T, U = T> = OwningRef<Box<T>, U>;
1138 /// Typedef of a owning reference that uses a `Vec` as the owner.
1139 pub type VecRef<T, U = T> = OwningRef<Vec<T>, U>;
1140 /// Typedef of a owning reference that uses a `String` as the owner.
1141 pub type StringRef = OwningRef<String, str>;
1142
1143 /// Typedef of a owning reference that uses a `Rc` as the owner.
1144 pub type RcRef<T, U = T> = OwningRef<Rc<T>, U>;
1145 /// Typedef of a owning reference that uses a `Arc` as the owner.
1146 pub type ArcRef<T, U = T> = OwningRef<Arc<T>, U>;
1147
1148 /// Typedef of a owning reference that uses a `Ref` as the owner.
1149 pub type RefRef<'a, T, U = T> = OwningRef<Ref<'a, T>, U>;
1150 /// Typedef of a owning reference that uses a `RefMut` as the owner.
1151 pub type RefMutRef<'a, T, U = T> = OwningRef<RefMut<'a, T>, U>;
1152 /// Typedef of a owning reference that uses a `MutexGuard` as the owner.
1153 pub type MutexGuardRef<'a, T, U = T> = OwningRef<MutexGuard<'a, T>, U>;
1154 /// Typedef of a owning reference that uses a `RwLockReadGuard` as the owner.
1155 pub type RwLockReadGuardRef<'a, T, U = T> = OwningRef<RwLockReadGuard<'a, T>, U>;
1156 /// Typedef of a owning reference that uses a `RwLockWriteGuard` as the owner.
1157 pub type RwLockWriteGuardRef<'a, T, U = T> = OwningRef<RwLockWriteGuard<'a, T>, U>;
1158
1159 /// Typedef of a mutable owning reference that uses a `Box` as the owner.
1160 pub type BoxRefMut<T, U = T> = OwningRefMut<Box<T>, U>;
1161 /// Typedef of a mutable owning reference that uses a `Vec` as the owner.
1162 pub type VecRefMut<T, U = T> = OwningRefMut<Vec<T>, U>;
1163 /// Typedef of a mutable owning reference that uses a `String` as the owner.
1164 pub type StringRefMut = OwningRefMut<String, str>;
1165
1166 /// Typedef of a mutable owning reference that uses a `RefMut` as the owner.
1167 pub type RefMutRefMut<'a, T, U = T> = OwningRefMut<RefMut<'a, T>, U>;
1168 /// Typedef of a mutable owning reference that uses a `MutexGuard` as the owner.
1169 pub type MutexGuardRefMut<'a, T, U = T> = OwningRefMut<MutexGuard<'a, T>, U>;
1170 /// Typedef of a mutable owning reference that uses a `RwLockWriteGuard` as the owner.
1171 pub type RwLockWriteGuardRefMut<'a, T, U = T> = OwningRef<RwLockWriteGuard<'a, T>, U>;
1172
1173 unsafe impl<'a, T: 'a> IntoErased<'a> for Box<T> {
1174     type Erased = Box<dyn Erased + 'a>;
1175     fn into_erased(self) -> Self::Erased {
1176         self
1177     }
1178 }
1179 unsafe impl<'a, T: 'a> IntoErased<'a> for Rc<T> {
1180     type Erased = Rc<dyn Erased + 'a>;
1181     fn into_erased(self) -> Self::Erased {
1182         self
1183     }
1184 }
1185 unsafe impl<'a, T: 'a> IntoErased<'a> for Arc<T> {
1186     type Erased = Arc<dyn Erased + 'a>;
1187     fn into_erased(self) -> Self::Erased {
1188         self
1189     }
1190 }
1191
1192 unsafe impl<'a, T: Send + 'a> IntoErasedSend<'a> for Box<T> {
1193     type Erased = Box<dyn Erased + Send + 'a>;
1194     fn into_erased_send(self) -> Self::Erased {
1195         self
1196     }
1197 }
1198
1199 unsafe impl<'a, T: Send + 'a> IntoErasedSendSync<'a> for Box<T> {
1200     type Erased = Box<dyn Erased + Sync + Send + 'a>;
1201     fn into_erased_send_sync(self) -> Self::Erased {
1202         let result: Box<dyn Erased + Send + 'a> = self;
1203         // This is safe since Erased can always implement Sync
1204         // Only the destructor is available and it takes &mut self
1205         unsafe {
1206             mem::transmute(result)
1207         }
1208     }
1209 }
1210
1211 unsafe impl<'a, T: Send + Sync + 'a> IntoErasedSendSync<'a> for Arc<T> {
1212     type Erased = Arc<dyn Erased + Send + Sync + 'a>;
1213     fn into_erased_send_sync(self) -> Self::Erased {
1214         self
1215     }
1216 }
1217
1218 /// Typedef of a owning reference that uses an erased `Box` as the owner.
1219 pub type ErasedBoxRef<U> = OwningRef<Box<dyn Erased>, U>;
1220 /// Typedef of a owning reference that uses an erased `Rc` as the owner.
1221 pub type ErasedRcRef<U> = OwningRef<Rc<dyn Erased>, U>;
1222 /// Typedef of a owning reference that uses an erased `Arc` as the owner.
1223 pub type ErasedArcRef<U> = OwningRef<Arc<dyn Erased>, U>;
1224
1225 /// Typedef of a mutable owning reference that uses an erased `Box` as the owner.
1226 pub type ErasedBoxRefMut<U> = OwningRefMut<Box<dyn Erased>, U>;
1227
1228 #[cfg(test)]
1229 mod tests;