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.
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:
14 fn return_owned_and_referenced<'a>() -> (Vec<u8>, &'a [u8]) {
15 let v = vec![1, 2, 3, 4];
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.
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:
29 # extern crate owning_ref;
30 # use owning_ref::OwningRef;
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]);
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.
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>`.
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.
59 extern crate owning_ref;
60 use owning_ref::BoxRef;
63 // Create an array owned by a Box.
64 let arr = Box::new([1, 2, 3, 4]) as Box<[i32]>;
66 // Transfer into a BoxRef.
67 let arr: BoxRef<[i32]> = BoxRef::new(arr);
68 assert_eq!(&*arr, &[1, 2, 3, 4]);
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]);
74 // Also works for Arc, Rc, String and Vec!
78 ## Caching a reference to a struct field
81 extern crate owning_ref;
82 use owning_ref::BoxRef;
91 let foo = Foo { tag: 1, x: 100, y: 200, z: 300 };
93 let or = BoxRef::new(Box::new(foo)).map(|foo| {
102 assert_eq!(*or, 200);
106 ## Caching a reference to an entry in a vector
109 extern crate owning_ref;
110 use owning_ref::VecRef;
113 let v = VecRef::new(vec![1, 2, 3, 4, 5]).map(|v| &v[3]);
118 ## Caching a subslice of a String
121 extern crate owning_ref;
122 use owning_ref::StringRef;
125 let s = StringRef::new("hello world".to_owned())
126 .map(|s| s.split(' ').nth(1).unwrap());
128 assert_eq!(&*s, "world");
132 ## Reference counted slices that share ownership of the backing storage
135 extern crate owning_ref;
136 use owning_ref::RcRef;
140 let rc: RcRef<[i32]> = RcRef::new(Rc::new([1, 2, 3, 4]) as Rc<[i32]>);
141 assert_eq!(&*rc, &[1, 2, 3, 4]);
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]);
150 let rc_c_a = rc_c.clone().map(|s| &s[1]);
151 assert_eq!(&*rc_c_a, &4);
155 ## Atomic reference counted slices that share ownership of the backing storage
158 extern crate owning_ref;
159 use owning_ref::ArcRef;
165 fn par_sum(rc: ArcRef<[i32]>) -> i32 {
168 } else if rc.len() == 1 {
171 let mid = rc.len() / 2;
172 let left = rc.clone().map(|s| &s[..mid]);
173 let right = rc.map(|s| &s[mid..]);
175 let left = thread::spawn(move || par_sum(left));
176 let right = thread::spawn(move || par_sum(right));
178 left.join().unwrap() + right.join().unwrap()
181 let rc: Arc<[i32]> = Arc::new([1, 2, 3, 4]);
182 let rc: ArcRef<[i32]> = rc.into();
184 assert_eq!(par_sum(rc), 10);
188 ## References into RAII locks
191 extern crate owning_ref;
192 use owning_ref::RefRef;
193 use std::cell::{RefCell, Ref};
196 let refcell = RefCell::new((1, 2, 3, 4));
197 // Also works with Mutex and RwLock
200 let refref = RefRef::new(refcell.borrow()).map(|x| &x.3);
201 assert_eq!(*refref, 4);
203 // We move the RAII lock and the reference to one of
204 // the subfields in the data it guards here:
208 assert_eq!(*refref, 4);
212 assert_eq!(*refcell.borrow(), (1, 2, 3, 4));
218 When the owned container implements `DerefMut`, it is also possible to make
219 a _mutable owning reference_. (e.g., with `Box`, `RefMut`, `MutexGuard`)
222 extern crate owning_ref;
223 use owning_ref::RefMutRefMut;
224 use std::cell::{RefCell, RefMut};
227 let refcell = RefCell::new((1, 2, 3, 4));
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);
237 assert_eq!(*refmut_refmut, 8);
242 assert_eq!(*refcell.borrow(), (1, 2, 3, 16));
248 pub use stable_deref_trait::{StableDeref as StableAddress, CloneStableDeref as CloneStableAddress};
250 /// An owning reference.
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.
256 /// The owner is usually a pointer that points at some base type.
258 /// For more details and examples, see the module and method docs.
259 pub struct OwningRef<O, T: ?Sized> {
264 /// An mutable owning reference.
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.
270 /// The owner is usually a pointer that points at some base type.
272 /// For more details and examples, see the module and method docs.
273 pub struct OwningRefMut<O, T: ?Sized> {
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.
282 impl<T> Erased for T {}
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`.
291 /// Performs the type erasure.
292 fn into_erased(self) -> Self::Erased;
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`.
302 /// Performs the type erasure.
303 fn into_erased_send(self) -> Self::Erased;
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;
317 /////////////////////////////////////////////////////////////////////////////
319 /////////////////////////////////////////////////////////////////////////////
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.
327 /// extern crate owning_ref;
328 /// use owning_ref::OwningRef;
331 /// let owning_ref = OwningRef::new(Box::new(42));
332 /// assert_eq!(*owning_ref, 42);
335 pub fn new(o: O) -> Self
336 where O: StableAddress,
337 O: Deref<Target = T>,
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.
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>,
359 /// Converts `self` into a new owning reference that points at something reachable
360 /// from the previous one.
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.
367 /// extern crate owning_ref;
368 /// use owning_ref::OwningRef;
371 /// let owning_ref = OwningRef::new(Box::new([1, 2, 3, 4]));
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);
379 pub fn map<F, U: ?Sized>(self, f: F) -> OwningRef<O, U>
380 where O: StableAddress,
389 /// Tries to convert `self` into a new owning reference that points
390 /// at something reachable from the previous one.
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.
397 /// extern crate owning_ref;
398 /// use owning_ref::OwningRef;
401 /// let owning_ref = OwningRef::new(Box::new([1, 2, 3, 4]));
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(()) }
408 /// assert_eq!(*owning_ref.unwrap(), 3);
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>
416 reference: f(&self)?,
421 /// Converts `self` into a new owning reference with a different owner type.
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,
432 reference: self.reference,
433 owner: f(self.owner),
437 /// Converts `self` into a new owning reference where the owner is wrapped
438 /// in an additional `Box<O>`.
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> {
444 reference: self.reference,
445 owner: Box::new(self.owner),
449 /// Erases the concrete base type of the owner with a trait object.
451 /// This allows mixing of owned references with different owner base types.
455 /// extern crate owning_ref;
456 /// use owning_ref::{OwningRef, Erased};
459 /// // N.B., using the concrete types here for explicitness.
460 /// // For less verbose code type aliases like `BoxRef` are provided.
462 /// let owning_ref_a: OwningRef<Box<[i32; 4]>, [i32; 4]>
463 /// = OwningRef::new(Box::new([1, 2, 3, 4]));
465 /// let owning_ref_b: OwningRef<Box<Vec<(i32, bool)>>, Vec<(i32, bool)>>
466 /// = OwningRef::new(Box::new(vec![(0, false), (1, true)]));
468 /// let owning_ref_a: OwningRef<Box<[i32; 4]>, i32>
469 /// = owning_ref_a.map(|a| &a[0]);
471 /// let owning_ref_b: OwningRef<Box<Vec<(i32, bool)>>, i32>
472 /// = owning_ref_b.map(|a| &a[1].0);
474 /// let owning_refs: [OwningRef<Box<Erased>, i32>; 2]
475 /// = [owning_ref_a.erase_owner(), owning_ref_b.erase_owner()];
477 /// assert_eq!(*owning_refs[0], 1);
478 /// assert_eq!(*owning_refs[1], 1);
481 pub fn erase_owner<'a>(self) -> OwningRef<O::Erased, T>
482 where O: IntoErased<'a>,
485 reference: self.reference,
486 owner: self.owner.into_erased(),
490 /// Erases the concrete base type of the owner with a trait object which implements `Send`.
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>,
497 reference: self.reference,
498 owner: self.owner.into_erased_send(),
502 /// Erases the concrete base type of the owner with a trait object
503 /// which implements `Send` and `Sync`.
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>,
510 reference: self.reference,
511 owner: self.owner.into_erased_send_sync(),
515 // UNIMPLEMENTED: wrap_owner
517 // FIXME: Naming convention?
518 /// A getter for the underlying owner.
519 pub fn owner(&self) -> &O {
523 // FIXME: Naming convention?
524 /// Discards the reference and retrieves the owner.
525 pub fn into_inner(self) -> O {
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.
536 /// extern crate owning_ref;
537 /// use owning_ref::OwningRefMut;
540 /// let owning_ref_mut = OwningRefMut::new(Box::new(42));
541 /// assert_eq!(*owning_ref_mut, 42);
544 pub fn new(mut o: O) -> Self
545 where O: StableAddress,
546 O: DerefMut<Target = T>,
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.
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>,
568 /// Converts `self` into a new _shared_ owning reference that points at
569 /// something reachable from the previous one.
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.
576 /// extern crate owning_ref;
577 /// use owning_ref::OwningRefMut;
580 /// let owning_ref_mut = OwningRefMut::new(Box::new([1, 2, 3, 4]));
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);
588 pub fn map<F, U: ?Sized>(mut self, f: F) -> OwningRef<O, U>
589 where O: StableAddress,
590 F: FnOnce(&mut T) -> &U
593 reference: f(&mut self),
598 /// Converts `self` into a new _mutable_ owning reference that points at
599 /// something reachable from the previous one.
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.
606 /// extern crate owning_ref;
607 /// use owning_ref::OwningRefMut;
610 /// let owning_ref_mut = OwningRefMut::new(Box::new([1, 2, 3, 4]));
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);
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
623 reference: f(&mut self),
628 /// Tries to convert `self` into a new _shared_ owning reference that points
629 /// at something reachable from the previous one.
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.
636 /// extern crate owning_ref;
637 /// use owning_ref::OwningRefMut;
640 /// let owning_ref_mut = OwningRefMut::new(Box::new([1, 2, 3, 4]));
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(()) }
647 /// assert_eq!(*owning_ref.unwrap(), 3);
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>
655 reference: f(&mut self)?,
660 /// Tries to convert `self` into a new _mutable_ owning reference that points
661 /// at something reachable from the previous one.
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.
668 /// extern crate owning_ref;
669 /// use owning_ref::OwningRefMut;
672 /// let owning_ref_mut = OwningRefMut::new(Box::new([1, 2, 3, 4]));
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(()) }
679 /// assert_eq!(*owning_ref_mut.unwrap(), 3);
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>
687 reference: f(&mut self)?,
692 /// Converts `self` into a new owning reference with a different owner type.
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,
703 reference: self.reference,
704 owner: f(self.owner),
708 /// Converts `self` into a new owning reference where the owner is wrapped
709 /// in an additional `Box<O>`.
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> {
715 reference: self.reference,
716 owner: Box::new(self.owner),
720 /// Erases the concrete base type of the owner with a trait object.
722 /// This allows mixing of owned references with different owner base types.
726 /// extern crate owning_ref;
727 /// use owning_ref::{OwningRefMut, Erased};
730 /// // N.B., using the concrete types here for explicitness.
731 /// // For less verbose code type aliases like `BoxRef` are provided.
733 /// let owning_ref_mut_a: OwningRefMut<Box<[i32; 4]>, [i32; 4]>
734 /// = OwningRefMut::new(Box::new([1, 2, 3, 4]));
736 /// let owning_ref_mut_b: OwningRefMut<Box<Vec<(i32, bool)>>, Vec<(i32, bool)>>
737 /// = OwningRefMut::new(Box::new(vec![(0, false), (1, true)]));
739 /// let owning_ref_mut_a: OwningRefMut<Box<[i32; 4]>, i32>
740 /// = owning_ref_mut_a.map_mut(|a| &mut a[0]);
742 /// let owning_ref_mut_b: OwningRefMut<Box<Vec<(i32, bool)>>, i32>
743 /// = owning_ref_mut_b.map_mut(|a| &mut a[1].0);
745 /// let owning_refs_mut: [OwningRefMut<Box<Erased>, i32>; 2]
746 /// = [owning_ref_mut_a.erase_owner(), owning_ref_mut_b.erase_owner()];
748 /// assert_eq!(*owning_refs_mut[0], 1);
749 /// assert_eq!(*owning_refs_mut[1], 1);
752 pub fn erase_owner<'a>(self) -> OwningRefMut<O::Erased, T>
753 where O: IntoErased<'a>,
756 reference: self.reference,
757 owner: self.owner.into_erased(),
761 // UNIMPLEMENTED: wrap_owner
763 // FIXME: Naming convention?
764 /// A getter for the underlying owner.
765 pub fn owner(&self) -> &O {
769 // FIXME: Naming convention?
770 /// Discards the reference and retrieves the owner.
771 pub fn into_inner(self) -> O {
776 /////////////////////////////////////////////////////////////////////////////
778 /////////////////////////////////////////////////////////////////////////////
780 use std::ops::{Deref, DerefMut};
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_.
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.
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.
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,
808 impl<O, H> Deref for OwningHandle<O, H>
809 where O: StableAddress, H: Deref,
811 type Target = H::Target;
812 fn deref(&self) -> &H::Target {
817 unsafe impl<O, H> StableAddress for OwningHandle<O, H>
818 where O: StableAddress, H: StableAddress,
821 impl<O, H> DerefMut for OwningHandle<O, H>
822 where O: StableAddress, H: DerefMut,
824 fn deref_mut(&mut self) -> &mut H::Target {
825 self.handle.deref_mut()
829 /// Trait to implement the conversion of owner to handle for common types.
831 /// The type of handle to be encapsulated by the OwningHandle.
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;
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;
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;
849 impl<O, H> OwningHandle<O, H>
851 O: StableAddress<Target: ToHandle<Handle = H>>,
854 /// Creates a new `OwningHandle` for a type that implements `ToHandle`. For types
855 /// that don't implement `ToHandle`, callers may invoke `new_with_fn`, which accepts
856 /// a callback to perform the conversion.
857 pub fn new(o: O) -> Self {
858 OwningHandle::new_with_fn(o, |x| unsafe { O::Target::to_handle(x) })
862 impl<O, H> OwningHandle<O, H>
864 O: StableAddress<Target: ToHandleMut<HandleMut = H>>,
867 /// Creates a new mutable `OwningHandle` for a type that implements `ToHandleMut`.
868 pub fn new_mut(o: O) -> Self {
869 OwningHandle::new_with_fn(o, |x| unsafe { O::Target::to_handle_mut(x) })
873 impl<O, H> OwningHandle<O, H>
874 where O: StableAddress, H: Deref,
876 /// Creates a new OwningHandle. The provided callback will be invoked with
877 /// a pointer to the object owned by `o`, and the returned value is stored
878 /// as the object to which this `OwningHandle` will forward `Deref` and
880 pub fn new_with_fn<F>(o: O, f: F) -> Self
881 where F: FnOnce(*const O::Target) -> H
885 h = f(o.deref() as *const O::Target);
894 /// Creates a new OwningHandle. The provided callback will be invoked with
895 /// a pointer to the object owned by `o`, and the returned value is stored
896 /// as the object to which this `OwningHandle` will forward `Deref` and
898 pub fn try_new<F, E>(o: O, f: F) -> Result<Self, E>
899 where F: FnOnce(*const O::Target) -> Result<H, E>
903 h = f(o.deref() as *const O::Target)?;
913 /////////////////////////////////////////////////////////////////////////////
915 /////////////////////////////////////////////////////////////////////////////
917 use std::convert::From;
918 use std::fmt::{self, Debug};
919 use std::marker::{Send, Sync};
920 use std::cmp::{Eq, PartialEq, Ord, PartialOrd, Ordering};
921 use std::hash::{Hash, Hasher};
922 use std::borrow::Borrow;
924 impl<O, T: ?Sized> Deref for OwningRef<O, T> {
927 fn deref(&self) -> &T {
934 impl<O, T: ?Sized> Deref for OwningRefMut<O, T> {
937 fn deref(&self) -> &T {
944 impl<O, T: ?Sized> DerefMut for OwningRefMut<O, T> {
945 fn deref_mut(&mut self) -> &mut T {
952 unsafe impl<O, T: ?Sized> StableAddress for OwningRef<O, T> {}
954 impl<O, T: ?Sized> AsRef<T> for OwningRef<O, T> {
955 fn as_ref(&self) -> &T {
960 impl<O, T: ?Sized> AsRef<T> for OwningRefMut<O, T> {
961 fn as_ref(&self) -> &T {
966 impl<O, T: ?Sized> AsMut<T> for OwningRefMut<O, T> {
967 fn as_mut(&mut self) -> &mut T {
972 impl<O, T: ?Sized> Borrow<T> for OwningRef<O, T> {
973 fn borrow(&self) -> &T {
978 impl<O, T: ?Sized> From<O> for OwningRef<O, T>
979 where O: StableAddress,
980 O: Deref<Target = T>,
982 fn from(owner: O) -> Self {
983 OwningRef::new(owner)
987 impl<O, T: ?Sized> From<O> for OwningRefMut<O, T>
988 where O: StableAddress,
989 O: DerefMut<Target = T>
991 fn from(owner: O) -> Self {
992 OwningRefMut::new(owner)
996 impl<O, T: ?Sized> From<OwningRefMut<O, T>> for OwningRef<O, T>
997 where O: StableAddress,
998 O: DerefMut<Target = T>
1000 fn from(other: OwningRefMut<O, T>) -> Self {
1003 reference: other.reference,
1008 // ^ FIXME: Is a Into impl for calling into_inner() possible as well?
1010 impl<O, T: ?Sized> Debug for OwningRef<O, T>
1014 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1016 "OwningRef {{ owner: {:?}, reference: {:?} }}",
1022 impl<O, T: ?Sized> Debug for OwningRefMut<O, T>
1026 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1028 "OwningRefMut {{ owner: {:?}, reference: {:?} }}",
1034 impl<O, T: ?Sized> Clone for OwningRef<O, T>
1035 where O: CloneStableAddress,
1037 fn clone(&self) -> Self {
1039 owner: self.owner.clone(),
1040 reference: self.reference,
1045 unsafe impl<O, T: ?Sized> CloneStableAddress for OwningRef<O, T>
1046 where O: CloneStableAddress {}
1048 unsafe impl<O, T: ?Sized> Send for OwningRef<O, T>
1049 where O: Send, for<'a> (&'a T): Send {}
1050 unsafe impl<O, T: ?Sized> Sync for OwningRef<O, T>
1051 where O: Sync, for<'a> (&'a T): Sync {}
1053 unsafe impl<O, T: ?Sized> Send for OwningRefMut<O, T>
1054 where O: Send, for<'a> (&'a mut T): Send {}
1055 unsafe impl<O, T: ?Sized> Sync for OwningRefMut<O, T>
1056 where O: Sync, for<'a> (&'a mut T): Sync {}
1058 impl Debug for dyn Erased {
1059 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1060 write!(f, "<Erased>",)
1064 impl<O, T: ?Sized> PartialEq for OwningRef<O, T> where T: PartialEq {
1065 fn eq(&self, other: &Self) -> bool {
1066 (&*self as &T).eq(&*other as &T)
1070 impl<O, T: ?Sized> Eq for OwningRef<O, T> where T: Eq {}
1072 impl<O, T: ?Sized> PartialOrd for OwningRef<O, T> where T: PartialOrd {
1073 fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
1074 (&*self as &T).partial_cmp(&*other as &T)
1078 impl<O, T: ?Sized> Ord for OwningRef<O, T> where T: Ord {
1079 fn cmp(&self, other: &Self) -> Ordering {
1080 (&*self as &T).cmp(&*other as &T)
1084 impl<O, T: ?Sized> Hash for OwningRef<O, T> where T: Hash {
1085 fn hash<H: Hasher>(&self, state: &mut H) {
1086 (&*self as &T).hash(state);
1090 impl<O, T: ?Sized> PartialEq for OwningRefMut<O, T> where T: PartialEq {
1091 fn eq(&self, other: &Self) -> bool {
1092 (&*self as &T).eq(&*other as &T)
1096 impl<O, T: ?Sized> Eq for OwningRefMut<O, T> where T: Eq {}
1098 impl<O, T: ?Sized> PartialOrd for OwningRefMut<O, T> where T: PartialOrd {
1099 fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
1100 (&*self as &T).partial_cmp(&*other as &T)
1104 impl<O, T: ?Sized> Ord for OwningRefMut<O, T> where T: Ord {
1105 fn cmp(&self, other: &Self) -> Ordering {
1106 (&*self as &T).cmp(&*other as &T)
1110 impl<O, T: ?Sized> Hash for OwningRefMut<O, T> where T: Hash {
1111 fn hash<H: Hasher>(&self, state: &mut H) {
1112 (&*self as &T).hash(state);
1116 /////////////////////////////////////////////////////////////////////////////
1117 // std types integration and convenience type defs
1118 /////////////////////////////////////////////////////////////////////////////
1120 use std::boxed::Box;
1123 use std::sync::{MutexGuard, RwLockReadGuard, RwLockWriteGuard};
1124 use std::cell::{Ref, RefCell, RefMut};
1126 impl<T: 'static> ToHandle for RefCell<T> {
1127 type Handle = Ref<'static, T>;
1128 unsafe fn to_handle(x: *const Self) -> Self::Handle { (*x).borrow() }
1131 impl<T: 'static> ToHandleMut for RefCell<T> {
1132 type HandleMut = RefMut<'static, T>;
1133 unsafe fn to_handle_mut(x: *const Self) -> Self::HandleMut { (*x).borrow_mut() }
1136 // N.B., implementing ToHandle{,Mut} for Mutex and RwLock requires a decision
1137 // about which handle creation to use (i.e., read() vs try_read()) as well as
1138 // what to do with error results.
1140 /// Typedef of a owning reference that uses a `Box` as the owner.
1141 pub type BoxRef<T, U = T> = OwningRef<Box<T>, U>;
1142 /// Typedef of a owning reference that uses a `Vec` as the owner.
1143 pub type VecRef<T, U = T> = OwningRef<Vec<T>, U>;
1144 /// Typedef of a owning reference that uses a `String` as the owner.
1145 pub type StringRef = OwningRef<String, str>;
1147 /// Typedef of a owning reference that uses a `Rc` as the owner.
1148 pub type RcRef<T, U = T> = OwningRef<Rc<T>, U>;
1149 /// Typedef of a owning reference that uses a `Arc` as the owner.
1150 pub type ArcRef<T, U = T> = OwningRef<Arc<T>, U>;
1152 /// Typedef of a owning reference that uses a `Ref` as the owner.
1153 pub type RefRef<'a, T, U = T> = OwningRef<Ref<'a, T>, U>;
1154 /// Typedef of a owning reference that uses a `RefMut` as the owner.
1155 pub type RefMutRef<'a, T, U = T> = OwningRef<RefMut<'a, T>, U>;
1156 /// Typedef of a owning reference that uses a `MutexGuard` as the owner.
1157 pub type MutexGuardRef<'a, T, U = T> = OwningRef<MutexGuard<'a, T>, U>;
1158 /// Typedef of a owning reference that uses a `RwLockReadGuard` as the owner.
1159 pub type RwLockReadGuardRef<'a, T, U = T> = OwningRef<RwLockReadGuard<'a, T>, U>;
1160 /// Typedef of a owning reference that uses a `RwLockWriteGuard` as the owner.
1161 pub type RwLockWriteGuardRef<'a, T, U = T> = OwningRef<RwLockWriteGuard<'a, T>, U>;
1163 /// Typedef of a mutable owning reference that uses a `Box` as the owner.
1164 pub type BoxRefMut<T, U = T> = OwningRefMut<Box<T>, U>;
1165 /// Typedef of a mutable owning reference that uses a `Vec` as the owner.
1166 pub type VecRefMut<T, U = T> = OwningRefMut<Vec<T>, U>;
1167 /// Typedef of a mutable owning reference that uses a `String` as the owner.
1168 pub type StringRefMut = OwningRefMut<String, str>;
1170 /// Typedef of a mutable owning reference that uses a `RefMut` as the owner.
1171 pub type RefMutRefMut<'a, T, U = T> = OwningRefMut<RefMut<'a, T>, U>;
1172 /// Typedef of a mutable owning reference that uses a `MutexGuard` as the owner.
1173 pub type MutexGuardRefMut<'a, T, U = T> = OwningRefMut<MutexGuard<'a, T>, U>;
1174 /// Typedef of a mutable owning reference that uses a `RwLockWriteGuard` as the owner.
1175 pub type RwLockWriteGuardRefMut<'a, T, U = T> = OwningRef<RwLockWriteGuard<'a, T>, U>;
1177 unsafe impl<'a, T: 'a> IntoErased<'a> for Box<T> {
1178 type Erased = Box<dyn Erased + 'a>;
1179 fn into_erased(self) -> Self::Erased {
1183 unsafe impl<'a, T: 'a> IntoErased<'a> for Rc<T> {
1184 type Erased = Rc<dyn Erased + 'a>;
1185 fn into_erased(self) -> Self::Erased {
1189 unsafe impl<'a, T: 'a> IntoErased<'a> for Arc<T> {
1190 type Erased = Arc<dyn Erased + 'a>;
1191 fn into_erased(self) -> Self::Erased {
1196 unsafe impl<'a, T: Send + 'a> IntoErasedSend<'a> for Box<T> {
1197 type Erased = Box<dyn Erased + Send + 'a>;
1198 fn into_erased_send(self) -> Self::Erased {
1203 unsafe impl<'a, T: Send + 'a> IntoErasedSendSync<'a> for Box<T> {
1204 type Erased = Box<dyn Erased + Sync + Send + 'a>;
1205 fn into_erased_send_sync(self) -> Self::Erased {
1206 let result: Box<dyn Erased + Send + 'a> = self;
1207 // This is safe since Erased can always implement Sync
1208 // Only the destructor is available and it takes &mut self
1210 mem::transmute(result)
1215 unsafe impl<'a, T: Send + Sync + 'a> IntoErasedSendSync<'a> for Arc<T> {
1216 type Erased = Arc<dyn Erased + Send + Sync + 'a>;
1217 fn into_erased_send_sync(self) -> Self::Erased {
1222 /// Typedef of a owning reference that uses an erased `Box` as the owner.
1223 pub type ErasedBoxRef<U> = OwningRef<Box<dyn Erased>, U>;
1224 /// Typedef of a owning reference that uses an erased `Rc` as the owner.
1225 pub type ErasedRcRef<U> = OwningRef<Rc<dyn Erased>, U>;
1226 /// Typedef of a owning reference that uses an erased `Arc` as the owner.
1227 pub type ErasedArcRef<U> = OwningRef<Arc<dyn Erased>, U>;
1229 /// Typedef of a mutable owning reference that uses an erased `Box` as the owner.
1230 pub type ErasedBoxRefMut<U> = OwningRefMut<Box<dyn Erased>, U>;