#[repr(transparent)]pub struct Unique<T: ?Sized> {
pointer: NonNull<T>,
_marker: PhantomData<T>,
}
ptr_internals
)Expand description
A wrapper around a raw non-null *mut T
that indicates that the possessor
of this wrapper owns the referent. Useful for building abstractions like
Box<T>
, Vec<T>
, String
, and HashMap<K, V>
.
Unlike *mut T
, Unique<T>
behaves “as if” it were an instance of T
.
It implements Send
/Sync
if T
is Send
/Sync
. It also implies
the kind of strong aliasing guarantees an instance of T
can expect:
the referent of the pointer should not be modified without a unique path to
its owning Unique.
If you’re uncertain of whether it’s correct to use Unique
for your purposes,
consider using NonNull
, which has weaker semantics.
Unlike *mut T
, the pointer must always be non-null, even if the pointer
is never dereferenced. This is so that enums may use this forbidden value
as a discriminant – Option<Unique<T>>
has the same size as Unique<T>
.
However the pointer may still dangle if it isn’t dereferenced.
Unlike *mut T
, Unique<T>
is covariant over T
. This should always be correct
for any type which upholds Unique’s aliasing requirements.
Fields§
§pointer: NonNull<T>
ptr_internals
)_marker: PhantomData<T>
ptr_internals
)Implementations§
source§impl<T: Sized> Unique<T>
impl<T: Sized> Unique<T>
sourcepub const fn dangling() -> Self
🔬This is a nightly-only experimental API. (ptr_internals
)
pub const fn dangling() -> Self
ptr_internals
)Creates a new Unique
that is dangling, but well-aligned.
This is useful for initializing types which lazily allocate, like
Vec::new
does.
Note that the pointer value may potentially represent a valid pointer to
a T
, which means this must not be used as a “not yet initialized”
sentinel value. Types that lazily allocate must track initialization by
some other means.
source§impl<T: ?Sized> Unique<T>
impl<T: ?Sized> Unique<T>
sourcepub const unsafe fn new_unchecked(ptr: *mut T) -> Self
🔬This is a nightly-only experimental API. (ptr_internals
)
pub const unsafe fn new_unchecked(ptr: *mut T) -> Self
ptr_internals
)sourcepub const fn new(ptr: *mut T) -> Option<Self>
🔬This is a nightly-only experimental API. (ptr_internals
)
pub const fn new(ptr: *mut T) -> Option<Self>
ptr_internals
)Creates a new Unique
if ptr
is non-null.
sourcepub const fn as_ptr(self) -> *mut T
🔬This is a nightly-only experimental API. (ptr_internals
)
pub const fn as_ptr(self) -> *mut T
ptr_internals
)Acquires the underlying *mut
pointer.
sourcepub const unsafe fn as_ref(&self) -> &T
🔬This is a nightly-only experimental API. (ptr_internals
)
pub const unsafe fn as_ref(&self) -> &T
ptr_internals
)Dereferences the content.
The resulting lifetime is bound to self so this behaves “as if”
it were actually an instance of T that is getting borrowed. If a longer
(unbound) lifetime is needed, use &*my_ptr.as_ptr()
.
sourcepub const unsafe fn as_mut(&mut self) -> &mut T
🔬This is a nightly-only experimental API. (ptr_internals
)
pub const unsafe fn as_mut(&mut self) -> &mut T
ptr_internals
)Mutably dereferences the content.
The resulting lifetime is bound to self so this behaves “as if”
it were actually an instance of T that is getting borrowed. If a longer
(unbound) lifetime is needed, use &mut *my_ptr.as_ptr()
.