allocator_api2/stable/
unique.rs

1/// A wrapper around a raw non-null `*mut T` that indicates that the possessor
2/// of this wrapper owns the referent. Useful for building abstractions like
3/// `Box<T>`, `Vec<T>`, `String`, and `HashMap<K, V>`.
4///
5/// Unlike `*mut T`, `Unique<T>` behaves "as if" it were an instance of `T`.
6/// It implements `Send`/`Sync` if `T` is `Send`/`Sync`. It also implies
7/// the kind of strong aliasing guarantees an instance of `T` can expect:
8/// the referent of the pointer should not be modified without a unique path to
9/// its owning Unique.
10///
11/// If you're uncertain of whether it's correct to use `Unique` for your purposes,
12/// consider using `NonNull`, which has weaker semantics.
13///
14/// Unlike `*mut T`, the pointer must always be non-null, even if the pointer
15/// is never dereferenced. This is so that enums may use this forbidden value
16/// as a discriminant -- `Option<Unique<T>>` has the same size as `Unique<T>`.
17/// However the pointer may still dangle if it isn't dereferenced.
18///
19/// Unlike `*mut T`, `Unique<T>` is covariant over `T`. This should always be correct
20/// for any type which upholds Unique's aliasing requirements.
21#[repr(transparent)]
22pub(crate) struct Unique<T: ?Sized> {
23    pointer: NonNull<T>,
24    _marker: PhantomData<T>,
25}
26
27/// `Unique` pointers are `Send` if `T` is `Send` because the data they
28/// reference is unaliased. Note that this aliasing invariant is
29/// unenforced by the type system; the abstraction using the
30/// `Unique` must enforce it.
31unsafe impl<T: Send + ?Sized> Send for Unique<T> {}
32
33/// `Unique` pointers are `Sync` if `T` is `Sync` because the data they
34/// reference is unaliased. Note that this aliasing invariant is
35/// unenforced by the type system; the abstraction using the
36/// `Unique` must enforce it.
37unsafe impl<T: Sync + ?Sized> Sync for Unique<T> {}
38
39impl<T: ?Sized> Unique<T> {
40    /// Creates a new `Unique`.
41    ///
42    /// # Safety
43    ///
44    /// `ptr` must be non-null.
45    #[inline]
46    pub const unsafe fn new_unchecked(ptr: *mut T) -> Self {
47        // SAFETY: the caller must guarantee that `ptr` is non-null.
48        unsafe {
49            Unique {
50                pointer: NonNull::new_unchecked(ptr),
51                _marker: PhantomData,
52            }
53        }
54    }
55
56    /// Acquires the underlying `*mut` pointer.
57    #[must_use = "`self` will be dropped if the result is not used"]
58    #[inline]
59    pub const fn as_ptr(self) -> *mut T {
60        self.pointer.as_ptr()
61    }
62
63    /// Acquires the underlying `*mut` pointer.
64    #[must_use = "`self` will be dropped if the result is not used"]
65    #[inline]
66    pub const fn as_non_null_ptr(self) -> NonNull<T> {
67        self.pointer
68    }
69
70    /// Dereferences the content.
71    ///
72    /// The resulting lifetime is bound to self so this behaves "as if"
73    /// it were actually an instance of T that is getting borrowed. If a longer
74    /// (unbound) lifetime is needed, use `&*my_ptr.as_ptr()`.
75    #[must_use]
76    #[inline]
77    pub const unsafe fn as_ref(&self) -> &T {
78        // SAFETY: the caller must guarantee that `self` meets all the
79        // requirements for a reference.
80        unsafe { &*(self.as_ptr() as *const T) }
81    }
82
83    /// Mutably dereferences the content.
84    ///
85    /// The resulting lifetime is bound to self so this behaves "as if"
86    /// it were actually an instance of T that is getting borrowed. If a longer
87    /// (unbound) lifetime is needed, use `&mut *my_ptr.as_ptr()`.
88    #[must_use]
89    #[inline]
90    pub unsafe fn as_mut(&mut self) -> &mut T {
91        // SAFETY: the caller must guarantee that `self` meets all the
92        // requirements for a mutable reference.
93        unsafe { self.pointer.as_mut() }
94    }
95}
96
97impl<T: ?Sized> Clone for Unique<T> {
98    #[inline]
99    fn clone(&self) -> Self {
100        *self
101    }
102}
103
104impl<T: ?Sized> Copy for Unique<T> {}
105
106use core::{marker::PhantomData, ptr::NonNull};
allocator_api2/stable/unique.rs

allocator_api2/stable/
unique.rs
