Struct manually_boxed::Ptr

pub struct Ptr<T: ?Sized> { /* private fields */ }

Pointer to manually-memory-managed T

Ptr<T> usually refers to an item on the heap, like Box<T>. It can be made from T with Ptr::new_heap(), or From<Box>. It is then freed again with .free_heap().

To access the contained data use, Ptr::borrow() and borrow_mut().

To mutably access the data of more than one node at once, use IsTokenMut::multi_static or IsTokenMut::multi_dynamic. To avoid runtime aliasing checks, and take manual control of aliasing, you can .borrow_mut() with TokenMut::new_unchecked(); or, p.as_ptr().as_ref() / p.as_ptr().as_mut().

This type is Copy. Copying it (or, indeed, cloning it) does not copy the underlying data. Nor is there any reference counting or garbage collection.

Ensuring that Ptrs are freed at the right time is up to the caller, But aliasing, and other Rust unsafe footguns, are (largely) handled by the library. See the module-level documentation.

Implementations

impl<T: ?Sized> Ptr<T>

pub fn new_heap(t: T) -> Self

where T: Sized,

Makes a new Ptr, moving the T to a new heap allocation

pub fn borrow<'a>(self, tok: impl IsTokenRef<'a>) -> &'a T

Borrows the contained data, immutably

pub fn borrow_mut<'a>(self, tok: impl IsTokenMut<'a>) -> &'a mut T

Borrows the contained data, mutably

pub fn as_ptr(self) -> NonNull<T>

Returns the raw data pointer

Useful if you want to compare pointers, or something.

If Ptr was made with new_heap or From<Box<_>>, this pointer has the same properties as Box’s. But of course many copies may exist.

Obtaining references

You may call .as_ref() or .as_mut() on the returned NonNull, to get &T or &mut T.

This is sound iff there are no conflicting borrows, and you know you won’t be freeing the data too soon. If you do this, you take responsibility for following Rust’s aliasing rules.

This approach is semantically equivalent to using TokenMut::new_unchecked().

pub unsafe fn free_heap<'a>(self, tok: impl IsTokenMut<'a>)

Frees a Ptr that was made with new_heap

The contained T is dropped. To keep it, use .free_heap_return().

SAFETY

self must have come from new_heap (or From<Box>) and be the only remaining copy of this Ptr (or the only one which will be used).

All copies of self will be invalidated. It is your responsibility to ensure that none of them will be used. (“used” means passed to any method in this library.)

The compiler will check that no borrows are live.

pub unsafe fn free_heap_return<'a>(self, tok: impl IsTokenMut<'a>) -> T

where T: Sized,

Frees a Ptr that was made with new_heap and returns the T

If T is not Sized, you must use free_heap (discarding T) or into_box (leaving it on the heap).

SAFETY

The same rules as free_heap apply.

pub unsafe fn into_box<'a>(self, tok: impl IsTokenMut<'a>) -> Box<T>

Converts a Ptr that was made with new_heap into a Box<T>

SAFETY

The same rules as free_heap apply.

pub unsafe fn from_raw(t: NonNull<T>) -> Self

Make a new Ptr out of a raw pointer

SAFETY

It is up to you to ensure that the pointer is valid for T, dereferencable, and has appropriate lifespan.

Trait Implementations

impl<T: ?Sized> Clone for Ptr<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> Debug for Ptr<T>

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

Formats the value using the given formatter.

impl<T: ?Sized> From<Box<T>> for Ptr<T>

fn from(b: Box<T>) -> Ptr<T>

Converts to this type from the input type.

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

impl<T: Send + ?Sized> Send for Ptr<T>

impl<T: Sync + ?Sized> Sync for Ptr<T>