Struct alias_ptr::AliasPtr [−][src]
#[repr(transparent)]pub struct AliasPtr<T: ?Sized>(_);
Expand description
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
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()
.
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.)
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”.
Trait Implementations
Auto Trait Implementations
impl<T: ?Sized> RefUnwindSafe for AliasPtr<T> where
T: RefUnwindSafe,
impl<T: ?Sized> UnwindSafe for AliasPtr<T> where
T: RefUnwindSafe,
Blanket Implementations
Mutably borrows from an owned value. Read more