Struct core::ptr::Shared

pub struct Shared<T: ?Sized> { /* fields omitted */ }

🔬 This is a nightly-only experimental API. (shared #27730)

needs an RFC to flesh out design

A wrapper around a raw *mut T that indicates that the possessor of this wrapper has shared ownership of the referent. Useful for building abstractions like Rc<T>, Arc<T>, or doubly-linked lists, which internally use aliased raw pointers to manage the memory that they own.

This is similar to Unique, except that it doesn't make any aliasing guarantees, and doesn't derive Send and Sync. Note that unlike &T, Shared has no special mutability requirements. Shared may mutate data aliased by other Shared pointers. More precise rules require Rust to develop an actual aliasing model.

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<Shared<T>> has the same size as Shared<T>. However the pointer may still dangle if it isn't dereferenced.

Unlike *mut T, Shared<T> is covariant over T. If this is incorrect for your use case, you should include some PhantomData in your type to provide invariance, such as PhantomData<Cell<T>> or PhantomData<&'a mut T>. Usually this won't be necessary; covariance is correct for Rc, Arc, and LinkedList because they provide a public API that follows the normal shared XOR mutable rules of Rust.

Methods

impl<T: Sized> Shared<T>

fn empty() -> Self

🔬 This is a nightly-only experimental API. (shared #27730)

Creates a new Shared that is dangling, but well-aligned.

This is useful for initializing types which lazily allocate, like Vec::new does.

impl<T: ?Sized> Shared<T>

unsafe fn new(ptr: *mut T) -> Self

🔬 This is a nightly-only experimental API. (shared #27730)

Creates a new Shared.

Safety

ptr must be non-null.

fn as_ptr(self) -> *mut T

🔬 This is a nightly-only experimental API. (shared #27730)

Acquires the underlying *mut pointer.

unsafe fn as_ref(&self) -> &T

🔬 This is a nightly-only experimental API. (shared #27730)

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.ptr().

unsafe fn as_mut(&mut self) -> &mut T

🔬 This is a nightly-only experimental API. (shared #27730)

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.ptr_mut().

unsafe fn as_mut_ptr(&self) -> *mut T

Deprecated since 1.19

: renamed to as_ptr for ergonomics/consistency

🔬 This is a nightly-only experimental API. (shared #27730)

Acquires the underlying pointer as a *mut pointer.

Trait Implementations

impl<T: ?Sized> !Send for Shared<T>

Shared pointers are not Send because the data they reference may be aliased.

impl<T: ?Sized> !Sync for Shared<T>

Shared pointers are not Sync because the data they reference may be aliased.

impl<T: ?Sized> Clone for Shared<T>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: ?Sized> Copy for Shared<T>

impl<T: ?Sized, U: ?Sized> CoerceUnsized<Shared<U>> for Shared<T> where
    T: Unsize<U>, 

impl<T: ?Sized> Pointer for Shared<T>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.