1 | use crate::fmt; |
2 | use crate::marker::{PhantomData, Unsize}; |
3 | use crate::ops::{CoerceUnsized, DispatchFromDyn}; |
4 | use crate::pin::PinCoerceUnsized; |
5 | use crate::ptr::NonNull; |
6 | |
7 | /// A wrapper around a raw non-null `*mut T` that indicates that the possessor |
8 | /// of this wrapper owns the referent. Useful for building abstractions like |
9 | /// `Box<T>`, `Vec<T>`, `String`, and `HashMap<K, V>`. |
10 | /// |
11 | /// Unlike `*mut T`, `Unique<T>` behaves "as if" it were an instance of `T`. |
12 | /// It implements `Send`/`Sync` if `T` is `Send`/`Sync`. It also implies |
13 | /// the kind of strong aliasing guarantees an instance of `T` can expect: |
14 | /// the referent of the pointer should not be modified without a unique path to |
15 | /// its owning Unique. |
16 | /// |
17 | /// If you're uncertain of whether it's correct to use `Unique` for your purposes, |
18 | /// consider using `NonNull`, which has weaker semantics. |
19 | /// |
20 | /// Unlike `*mut T`, the pointer must always be non-null, even if the pointer |
21 | /// is never dereferenced. This is so that enums may use this forbidden value |
22 | /// as a discriminant -- `Option<Unique<T>>` has the same size as `Unique<T>`. |
23 | /// However the pointer may still dangle if it isn't dereferenced. |
24 | /// |
25 | /// Unlike `*mut T`, `Unique<T>` is covariant over `T`. This should always be correct |
26 | /// for any type which upholds Unique's aliasing requirements. |
27 | #[unstable ( |
28 | feature = "ptr_internals" , |
29 | issue = "none" , |
30 | reason = "use `NonNull` instead and consider `PhantomData<T>` \ |
31 | (if you also use `#[may_dangle]`), `Send`, and/or `Sync`" |
32 | )] |
33 | #[doc (hidden)] |
34 | #[repr (transparent)] |
35 | // Lang item used experimentally by Miri to define the semantics of `Unique`. |
36 | #[lang = "ptr_unique" ] |
37 | pub struct Unique<T: ?Sized> { |
38 | pointer: NonNull<T>, |
39 | // NOTE: this marker has no consequences for variance, but is necessary |
40 | // for dropck to understand that we logically own a `T`. |
41 | // |
42 | // For details, see: |
43 | // https://github.com/rust-lang/rfcs/blob/master/text/0769-sound-generic-drop.md#phantom-data |
44 | _marker: PhantomData<T>, |
45 | } |
46 | |
47 | /// `Unique` pointers are `Send` if `T` is `Send` because the data they |
48 | /// reference is unaliased. Note that this aliasing invariant is |
49 | /// unenforced by the type system; the abstraction using the |
50 | /// `Unique` must enforce it. |
51 | #[unstable (feature = "ptr_internals" , issue = "none" )] |
52 | unsafe impl<T: Send + ?Sized> Send for Unique<T> {} |
53 | |
54 | /// `Unique` pointers are `Sync` if `T` is `Sync` because the data they |
55 | /// reference is unaliased. Note that this aliasing invariant is |
56 | /// unenforced by the type system; the abstraction using the |
57 | /// `Unique` must enforce it. |
58 | #[unstable (feature = "ptr_internals" , issue = "none" )] |
59 | unsafe impl<T: Sync + ?Sized> Sync for Unique<T> {} |
60 | |
61 | #[unstable (feature = "ptr_internals" , issue = "none" )] |
62 | impl<T: Sized> Unique<T> { |
63 | /// Creates a new `Unique` that is dangling, but well-aligned. |
64 | /// |
65 | /// This is useful for initializing types which lazily allocate, like |
66 | /// `Vec::new` does. |
67 | /// |
68 | /// Note that the pointer value may potentially represent a valid pointer to |
69 | /// a `T`, which means this must not be used as a "not yet initialized" |
70 | /// sentinel value. Types that lazily allocate must track initialization by |
71 | /// some other means. |
72 | #[must_use ] |
73 | #[inline ] |
74 | pub const fn dangling() -> Self { |
75 | // FIXME(const-hack) replace with `From` |
76 | Unique { pointer: NonNull::dangling(), _marker: PhantomData } |
77 | } |
78 | } |
79 | |
80 | #[unstable (feature = "ptr_internals" , issue = "none" )] |
81 | impl<T: ?Sized> Unique<T> { |
82 | /// Creates a new `Unique`. |
83 | /// |
84 | /// # Safety |
85 | /// |
86 | /// `ptr` must be non-null. |
87 | #[inline ] |
88 | pub const unsafe fn new_unchecked(ptr: *mut T) -> Self { |
89 | // SAFETY: the caller must guarantee that `ptr` is non-null. |
90 | unsafe { Unique { pointer: NonNull::new_unchecked(ptr), _marker: PhantomData } } |
91 | } |
92 | |
93 | /// Creates a new `Unique` if `ptr` is non-null. |
94 | #[inline ] |
95 | pub const fn new(ptr: *mut T) -> Option<Self> { |
96 | if let Some(pointer) = NonNull::new(ptr) { |
97 | Some(Unique { pointer, _marker: PhantomData }) |
98 | } else { |
99 | None |
100 | } |
101 | } |
102 | |
103 | /// Create a new `Unique` from a `NonNull` in const context. |
104 | #[inline ] |
105 | pub const fn from_non_null(pointer: NonNull<T>) -> Self { |
106 | Unique { pointer, _marker: PhantomData } |
107 | } |
108 | |
109 | /// Acquires the underlying `*mut` pointer. |
110 | #[must_use = "`self` will be dropped if the result is not used" ] |
111 | #[inline ] |
112 | pub const fn as_ptr(self) -> *mut T { |
113 | self.pointer.as_ptr() |
114 | } |
115 | |
116 | /// Acquires the underlying `*mut` pointer. |
117 | #[must_use = "`self` will be dropped if the result is not used" ] |
118 | #[inline ] |
119 | pub const fn as_non_null_ptr(self) -> NonNull<T> { |
120 | self.pointer |
121 | } |
122 | |
123 | /// Dereferences the content. |
124 | /// |
125 | /// The resulting lifetime is bound to self so this behaves "as if" |
126 | /// it were actually an instance of T that is getting borrowed. If a longer |
127 | /// (unbound) lifetime is needed, use `&*my_ptr.as_ptr()`. |
128 | #[must_use ] |
129 | #[inline ] |
130 | pub const unsafe fn as_ref(&self) -> &T { |
131 | // SAFETY: the caller must guarantee that `self` meets all the |
132 | // requirements for a reference. |
133 | unsafe { self.pointer.as_ref() } |
134 | } |
135 | |
136 | /// Mutably dereferences the content. |
137 | /// |
138 | /// The resulting lifetime is bound to self so this behaves "as if" |
139 | /// it were actually an instance of T that is getting borrowed. If a longer |
140 | /// (unbound) lifetime is needed, use `&mut *my_ptr.as_ptr()`. |
141 | #[must_use ] |
142 | #[inline ] |
143 | pub const unsafe fn as_mut(&mut self) -> &mut T { |
144 | // SAFETY: the caller must guarantee that `self` meets all the |
145 | // requirements for a mutable reference. |
146 | unsafe { self.pointer.as_mut() } |
147 | } |
148 | |
149 | /// Casts to a pointer of another type. |
150 | #[must_use = "`self` will be dropped if the result is not used" ] |
151 | #[inline ] |
152 | pub const fn cast<U>(self) -> Unique<U> { |
153 | // FIXME(const-hack): replace with `From` |
154 | // SAFETY: is `NonNull` |
155 | Unique { pointer: self.pointer.cast(), _marker: PhantomData } |
156 | } |
157 | } |
158 | |
159 | #[unstable (feature = "ptr_internals" , issue = "none" )] |
160 | impl<T: ?Sized> Clone for Unique<T> { |
161 | #[inline ] |
162 | fn clone(&self) -> Self { |
163 | *self |
164 | } |
165 | } |
166 | |
167 | #[unstable (feature = "ptr_internals" , issue = "none" )] |
168 | impl<T: ?Sized> Copy for Unique<T> {} |
169 | |
170 | #[unstable (feature = "ptr_internals" , issue = "none" )] |
171 | impl<T: ?Sized, U: ?Sized> CoerceUnsized<Unique<U>> for Unique<T> where T: Unsize<U> {} |
172 | |
173 | #[unstable (feature = "ptr_internals" , issue = "none" )] |
174 | impl<T: ?Sized, U: ?Sized> DispatchFromDyn<Unique<U>> for Unique<T> where T: Unsize<U> {} |
175 | |
176 | #[unstable (feature = "pin_coerce_unsized_trait" , issue = "123430" )] |
177 | unsafe impl<T: ?Sized> PinCoerceUnsized for Unique<T> {} |
178 | |
179 | #[unstable (feature = "ptr_internals" , issue = "none" )] |
180 | impl<T: ?Sized> fmt::Debug for Unique<T> { |
181 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
182 | fmt::Pointer::fmt(&self.as_ptr(), f) |
183 | } |
184 | } |
185 | |
186 | #[unstable (feature = "ptr_internals" , issue = "none" )] |
187 | impl<T: ?Sized> fmt::Pointer for Unique<T> { |
188 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
189 | fmt::Pointer::fmt(&self.as_ptr(), f) |
190 | } |
191 | } |
192 | |
193 | #[unstable (feature = "ptr_internals" , issue = "none" )] |
194 | impl<T: ?Sized> From<&mut T> for Unique<T> { |
195 | /// Converts a `&mut T` to a `Unique<T>`. |
196 | /// |
197 | /// This conversion is infallible since references cannot be null. |
198 | #[inline ] |
199 | fn from(reference: &mut T) -> Self { |
200 | Self::from(NonNull::from(reference)) |
201 | } |
202 | } |
203 | |
204 | #[unstable (feature = "ptr_internals" , issue = "none" )] |
205 | impl<T: ?Sized> From<NonNull<T>> for Unique<T> { |
206 | /// Converts a `NonNull<T>` to a `Unique<T>`. |
207 | /// |
208 | /// This conversion is infallible since `NonNull` cannot be null. |
209 | #[inline ] |
210 | fn from(pointer: NonNull<T>) -> Self { |
211 | Unique::from_non_null(pointer) |
212 | } |
213 | } |
214 | |