1use crate::fmt;
2use crate::marker::{PhantomData, Unsize};
3use crate::ops::{CoerceUnsized, DispatchFromDyn};
4use crate::ptr::NonNull;
5
6/// A wrapper around a raw non-null `*mut T` that indicates that the possessor
7/// of this wrapper owns the referent. Useful for building abstractions like
8/// `Box<T>`, `Vec<T>`, `String`, and `HashMap<K, V>`.
9///
10/// Unlike `*mut T`, `Unique<T>` behaves "as if" it were an instance of `T`.
11/// It implements `Send`/`Sync` if `T` is `Send`/`Sync`. It also implies
12/// the kind of strong aliasing guarantees an instance of `T` can expect:
13/// the referent of the pointer should not be modified without a unique path to
14/// its owning Unique.
15///
16/// If you're uncertain of whether it's correct to use `Unique` for your purposes,
17/// consider using `NonNull`, which has weaker semantics.
18///
19/// Unlike `*mut T`, the pointer must always be non-null, even if the pointer
20/// is never dereferenced. This is so that enums may use this forbidden value
21/// as a discriminant -- `Option<Unique<T>>` has the same size as `Unique<T>`.
22/// However the pointer may still dangle if it isn't dereferenced.
23///
24/// Unlike `*mut T`, `Unique<T>` is covariant over `T`. This should always be correct
25/// for any type which upholds Unique's aliasing requirements.
26#[unstable(
27 feature = "ptr_internals",
28 issue = "none",
29 reason = "use `NonNull` instead and consider `PhantomData<T>` \
30 (if you also use `#[may_dangle]`), `Send`, and/or `Sync`"
31)]
32#[doc(hidden)]
33#[repr(transparent)]
34// Lang item used experimentally by Miri to define the semantics of `Unique`.
35#[lang = "ptr_unique"]
36pub struct Unique<T: ?Sized> {
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 + ?Sized> 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 + ?Sized> 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 pointer value may potentially represent a valid pointer to
68 /// a `T`, which means this must not be used as a "not yet initialized"
69 /// sentinel value. Types that lazily allocate must track initialization by
70 /// 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: ?Sized> 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 /// Acquires the underlying `*mut` pointer.
103 #[must_use = "`self` will be dropped if the result is not used"]
104 #[inline]
105 pub const fn as_ptr(self) -> *mut T {
106 self.pointer.as_ptr()
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_non_null_ptr(self) -> NonNull<T> {
113 self.pointer
114 }
115
116 /// Dereferences the content.
117 ///
118 /// The resulting lifetime is bound to self so this behaves "as if"
119 /// it were actually an instance of T that is getting borrowed. If a longer
120 /// (unbound) lifetime is needed, use `&*my_ptr.as_ptr()`.
121 #[must_use]
122 #[inline]
123 pub const unsafe fn as_ref(&self) -> &T {
124 // SAFETY: the caller must guarantee that `self` meets all the
125 // requirements for a reference.
126 unsafe { self.pointer.as_ref() }
127 }
128
129 /// Mutably dereferences the content.
130 ///
131 /// The resulting lifetime is bound to self so this behaves "as if"
132 /// it were actually an instance of T that is getting borrowed. If a longer
133 /// (unbound) lifetime is needed, use `&mut *my_ptr.as_ptr()`.
134 #[must_use]
135 #[inline]
136 pub const unsafe fn as_mut(&mut self) -> &mut T {
137 // SAFETY: the caller must guarantee that `self` meets all the
138 // requirements for a mutable reference.
139 unsafe { self.pointer.as_mut() }
140 }
141
142 /// Casts to a pointer of another type.
143 #[must_use = "`self` will be dropped if the result is not used"]
144 #[inline]
145 pub const fn cast<U>(self) -> Unique<U> {
146 // FIXME(const-hack): replace with `From`
147 // SAFETY: is `NonNull`
148 Unique { pointer: self.pointer.cast(), _marker: PhantomData }
149 }
150}
151
152#[unstable(feature = "ptr_internals", issue = "none")]
153impl<T: ?Sized> Clone for Unique<T> {
154 #[inline]
155 fn clone(&self) -> Self {
156 *self
157 }
158}
159
160#[unstable(feature = "ptr_internals", issue = "none")]
161impl<T: ?Sized> Copy for Unique<T> {}
162
163#[unstable(feature = "ptr_internals", issue = "none")]
164impl<T: ?Sized, U: ?Sized> CoerceUnsized<Unique<U>> for Unique<T> where T: Unsize<U> {}
165
166#[unstable(feature = "ptr_internals", issue = "none")]
167impl<T: ?Sized, U: ?Sized> DispatchFromDyn<Unique<U>> for Unique<T> where T: Unsize<U> {}
168
169#[unstable(feature = "ptr_internals", issue = "none")]
170impl<T: ?Sized> fmt::Debug for Unique<T> {
171 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
172 fmt::Pointer::fmt(&self.as_ptr(), f)
173 }
174}
175
176#[unstable(feature = "ptr_internals", issue = "none")]
177impl<T: ?Sized> fmt::Pointer for Unique<T> {
178 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
179 fmt::Pointer::fmt(&self.as_ptr(), f)
180 }
181}
182
183#[unstable(feature = "ptr_internals", issue = "none")]
184impl<T: ?Sized> From<&mut T> for Unique<T> {
185 /// Converts a `&mut T` to a `Unique<T>`.
186 ///
187 /// This conversion is infallible since references cannot be null.
188 #[inline]
189 fn from(reference: &mut T) -> Self {
190 Self::from(NonNull::from(reference))
191 }
192}
193
194#[unstable(feature = "ptr_internals", issue = "none")]
195impl<T: ?Sized> From<NonNull<T>> for Unique<T> {
196 /// Converts a `NonNull<T>` to a `Unique<T>`.
197 ///
198 /// This conversion is infallible since `NonNull` cannot be null.
199 #[inline]
200 fn from(pointer: NonNull<T>) -> Self {
201 Unique { pointer, _marker: PhantomData }
202 }
203}
204