Struct alias_ptr::AliasPtr

#[repr(transparent)]
pub struct AliasPtr<T: ?Sized>(_);

An untracked shared ownership pointer, pointing to heap memory manually freed.

The type AliasPtr<T> provides shared ownership of a value of type T, allocated in the heap. Invoking copy on AliasPtr produces a new AliasPtr instance, which points to the same allocation on the heap as the source AliasPtr. When you call delete on any of the copies, the value stored in that allocation is dropped, and all of the copies can no longer be safely dereferenced.

AliasPtr is primarily intended as an unsafe building block for safe abstractions, in order to avoid the runtime overhead of Rc or Arc in cases where the lifetimes are known statically.

Shared references in Rust disallow mutation by default, and AliasPtr is no exception: you cannot generally obtain a mutable reference to something inside an AliasPtr. If you need mutability, put a Cell/RefCell (not thread-safe), Mutex/RwLock/Atomic (thread-safe), or UnsafeCell (unsafe) inside the AliasPtr.

Usage

For each T on the heap, you are responsible for calling delete() on exactly one AliasPtr pointing to it, and not dereferencing it or its aliases after.

In Rust terms, AliasPtr<T> acts like a &T that allows dangling and deletion, a Rc<T> or Arc<T> with manual deletion, or like a more convenient raw pointer which is assumed to be valid.

In C++ terms, AliasPtr<T> operates like T* or T const*, with shared ownership over T, where the programmer decides which one to delete.

Thread Safety

Since AliasPtr<T> only exposes the same set of safe operations as a &T (delete() is unsafe), it would technically be sound to expose the same Send/Sync bounds as &T: impl Send/Sync for AliasPtr<T> where T: Sync.

However, I added additional T: Send bounds for both impl Send/Sync (matching Arc), as a lint to guard against sending or cloning an AliasPtr<T> to another thread, then calling delete() there.

If these bounds are inappropriate for your data structure, you can unsafe impl Send/Sync for your type containing AliasPtr.

Implementation

AliasPtr<T> has the same size as &T, and is interconvertible with a Box<T>.

AliasPtr wraps a raw pointer rather than a &T, because it’s not legal to pass a & into Box::from_raw(), and a dangling & may be UB. See “How to Dismantle an Atomic Bomb” for details.

Implementations

impl<T: Sized> AliasPtr<T>

pub fn new(x: T) -> AliasPtr<T>

Allocates memory on the heap and then places x into it.

This doesn’t actually allocate if T is zero-sized.

Examples

let five = AliasPtr::new(5);

impl<T: ?Sized> AliasPtr<T>

pub unsafe fn from_raw(p: *mut T) -> Self

Constructs an AliasPtr from a raw pointer.

Safety

p must be non-null and valid (its target is readable and writable).

In order for calling delete() to be sound, p must be obtained from Box::into_raw().

pub fn copy(&self) -> Self

Copy the pointer without copying the underlying data. (This is equivalent to calling clone(). This type doesn’t implement Copy to ensure all copies are explicit.)

pub unsafe fn delete(&mut self)

Call the destructor of T and free the allocated memory.

Safety

The AliasPtr must be derived from Box::into_raw() (from the global allocator). After calling delete(), neither self nor aliasing pointers can be safely dereferenced (a safe but unsound operation).

This method should logically take self by move, but that would unfortunately prevent drop(&mut Parent) from calling delete(self). Drop only provides &mut Parent, which doesn’t allow moving fields out. For discussion, see “Re-use struct fields on drop”.

pub fn as_ptr(this: &Self) -> *const T

Provides a raw pointer to the data.

The pointer is valid until delete() is called on the this or any of its aliases.

Trait Implementations

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

fn clone(&self) -> Self

Copy the pointer without copying the underlying data.

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

Performs copy-assignment from source.

impl<T: ?Sized> Deref for AliasPtr<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T: ?Sized> From<Box<T, Global>> for AliasPtr<T>

fn from(item: Box<T>) -> Self

Performs the conversion.

impl<T: ?Sized> Send for AliasPtr<T> where
    T: Send + Sync, 

impl<T: ?Sized> Sync for AliasPtr<T> where
    T: Send + Sync,