1use crate::fmt;
2use crate::marker::{PhantomData, Unsize};
3use crate::ops::{CoerceUnsized, DispatchFromDyn};
4use crate::pin::PinCoerceUnsized;
5use 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"]
37pub 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")]
52unsafe 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")]
59unsafe impl<T: Sync + ?Sized> Sync for Unique<T> {}
60
61#[unstable(feature = "ptr_internals", issue = "none")]
62impl<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")]
81impl<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")]
160impl<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")]
168impl<T: ?Sized> Copy for Unique<T> {}
169
170#[unstable(feature = "ptr_internals", issue = "none")]
171impl<T: ?Sized, U: ?Sized> CoerceUnsized<Unique<U>> for Unique<T> where T: Unsize<U> {}
172
173#[unstable(feature = "ptr_internals", issue = "none")]
174impl<T: ?Sized, U: ?Sized> DispatchFromDyn<Unique<U>> for Unique<T> where T: Unsize<U> {}
175
176#[unstable(feature = "pin_coerce_unsized_trait", issue = "123430")]
177unsafe impl<T: ?Sized> PinCoerceUnsized for Unique<T> {}
178
179#[unstable(feature = "ptr_internals", issue = "none")]
180impl<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")]
187impl<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")]
194impl<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")]
205impl<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