core::ptr::Shared - Rust
Description: API documentation for the Rust `Shared` struct in crate `core`.
Keywords: rust, rustlang, rust-lang, Shared

# Struct core::ptr::Shared [−] [src]

    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>`
[src]

#### `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>`
[src]

#### `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>`
[src]

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

### `impl<T: ?Sized> !Sync for Shared<T>`
[src]

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

### `impl<T: ?Sized> Clone for Shared<T>`
[src]

#### `fn clone(&self) -> Self`

Returns a copy of the value. Read more

#### `fn clone_from(&mut self, source: &Self)`
1.0.0

Performs copy-assignment from `source`. Read more

### `impl<T: ?Sized> Copy for Shared<T>`
[src]

### `impl<T: ?Sized, U: ?Sized> CoerceUnsized<Shared<U>> for Shared<T> where
T: Unsize<U>,`
[src]

### `impl<T: ?Sized> Pointer for Shared<T>`
[src]

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

Formats the value using the given formatter.

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result
+
  Collapse/expand all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)