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