Struct DynamicManagedGc 

pub struct DynamicManagedGc { /* private fields */ }

Type-erased garbage collected box.

The ManagedGc counterpart for script values. See the module docs for the ownership model.

Implementations

impl DynamicManagedGc

pub fn new<T: Finalize>(data: T) -> Self

Allocates a value and owns it.

pub unsafe fn new_cyclic<T: Finalize>(f: impl FnOnce(Self) -> T) -> Self

Allocates a value that can point back at itself.

f is handed a reference to the box before the value exists, so it can store it inside the value it returns.

Safety

The handle passed to f points at memory that is not written yet. Storing it is fine, but reading or writing through it before f returns is undefined.

pub fn new_raw( type_hash: TypeHash, lifetime: Lifetime, memory: *mut u8, layout: Layout, finalizer: impl Into<Finalizer>, ) -> Self

Takes ownership of an existing allocation.

The box will free memory and run finalizer when it is dropped.

Panics

Panics when memory is null.

pub fn new_uninitialized( type_hash: TypeHash, layout: Layout, finalizer: impl Into<Finalizer>, ) -> Self

Allocates room for a value without writing one into it.

The finalizer still runs on drop, so the caller must fill the memory before the box is dropped or read.

pub unsafe fn borrowed_raw( type_hash: TypeHash, memory: *mut u8, layout: Layout, finalizer: impl Into<Finalizer>, ) -> Self

Borrows an existing allocation without taking ownership of it.

The box acts like an owner while it lives: it hands out references, and it invalidates every one of them when it drops. But it never runs the finalizer, never frees memory, and refuses Self::consume. The caller keeps the value and the job of destroying it.

This is how a host lends a value to a script for the length of a call. The script gets Self::reference handles, and those report the value as gone the moment this box drops. A reference holds a Weak on the lifetime, so dropping the box is what kills the reference.

finalizer is never run here. It is stored so that Self::finalizer keeps describing the value, the same as it does for an owning box.

Safety

memory must point at an initialized value that type_hash and layout describe. The memory must stay valid, and the caller must not reach it by any other path, until this box is dropped. The box carries no lifetime, so nothing checks either rule.

Panics

Panics when memory is null.

pub unsafe fn borrowed<T: Finalize>(value: &mut T) -> Self

Borrows a value the caller keeps. See Self::borrowed_raw.

Safety

The box carries no lifetime, so it can outlive value. The caller must drop the box first, and must not reach value by any other path while the box lives.

pub fn reference(&self) -> Self

Takes another handle that references the same value without owning it.

pub fn consume<T>(self) -> Result<T, Self>

Takes the value out and frees the allocation.

Gives the box back when it does not own the value, the type does not match, or something is accessing it.

pub fn into_typed<T>(self) -> ManagedGc<T>

Puts a type back on the box.

pub fn renew(&mut self)

Replaces the lifetime, killing every reference taken so far. Does nothing on a referencing handle.

pub fn type_hash(&self) -> TypeHash

Returns the type of the value.

pub fn lifetime(&self) -> ManagedGcLifetime<'_>

Returns the borrow state, and with it whether this handle owns the value.

pub fn layout(&self) -> &Layout

Returns the layout of the allocation.

pub fn finalizer(&self) -> &Finalizer

Returns the drop function of the stored type.

pub unsafe fn memory(&self) -> &[u8]

Returns the value as raw bytes.

Safety

Bypasses the borrow state, and does not check that the value is still alive.

pub unsafe fn memory_mut(&mut self) -> &mut [u8]

Returns the value as mutable raw bytes.

Safety

Bypasses the borrow state, does not check that the value is still alive, and writing bytes that are not a valid value of the stored type makes every later access undefined.

pub fn exists(&self) -> bool

Returns true while the value is alive.

Always true for the owner.

pub fn is_owning(&self) -> bool

Returns true when this handle owns the value.

pub fn is_borrowed(&self) -> bool

Returns true when this box borrows memory it does not own.

Such a box never frees the memory and refuses Self::consume. See Self::borrowed_raw.

pub fn is_referencing(&self) -> bool

Returns true when this handle only references the value.

pub fn is_owned_by(&self, other: &Self) -> bool

Returns true when this handle references the value that other owns.

pub fn transfer_ownership(&mut self, new_owner: &mut Self) -> bool

Hands ownership over to a handle that references this value.

Returns false unless this handle owns the value and new_owner references it.

pub fn is<T>(&self) -> bool

Returns true when the value is a T.

pub fn try_read<T>(&self) -> Option<ValueReadAccess<'_, T>>

Guards the value for reading, or returns None when it is busy or gone.

Panics

Panics when the value is not a T.

pub fn try_write<T>(&mut self) -> Option<ValueWriteAccess<'_, T>>

Guards the value for writing, or returns None when it is busy or gone.

Panics

Panics when the value is not a T.

pub fn read<const LOCKING: bool, T>(&self) -> ValueReadAccess<'_, T>

Guards the value for reading, spinning until it is free when LOCKING.

Panics

Panics when the value is not a T, is gone, or is busy and LOCKING is false.

pub fn write<const LOCKING: bool, T>(&mut self) -> ValueWriteAccess<'_, T>

Guards the value for writing, spinning until it is free when LOCKING.

Panics

Panics when the value is not a T, is gone, or is busy and LOCKING is false.

pub fn try_borrow(&self) -> Option<DynamicManagedRef>

Takes a shared handle, or returns None when the value is busy or gone.

pub fn try_borrow_mut(&self) -> Option<DynamicManagedRefMut>

Takes an exclusive handle, or returns None when the value is busy or gone.

pub fn borrow<const LOCKING: bool>(&self) -> DynamicManagedRef

Takes a shared handle, spinning until it is free when LOCKING.

Panics

Panics when the value is gone, or when it is busy and LOCKING is false.

pub fn borrow_mut<const LOCKING: bool>(&mut self) -> DynamicManagedRefMut

Takes an exclusive handle, spinning until it is free when LOCKING.

Panics

Panics when the value is gone, or when it is busy and LOCKING is false.

pub fn lazy(&self) -> DynamicManagedLazy

Takes an unclaimed handle, which claims nothing and never blocks.

Panics

Panics when the value is gone.

pub unsafe fn as_ptr_raw(&self) -> *const u8

Returns the allocation pointer, checking nothing.

Safety

Neither the type, the borrow state, nor whether the value is still alive is checked.

pub unsafe fn as_mut_ptr_raw(&mut self) -> *mut u8

Returns the mutable allocation pointer, checking nothing.

Safety

Neither the type, the borrow state, nor whether the value is still alive is checked.

Trait Implementations

impl Drop for DynamicManagedGc

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl From<DynamicManagedGc> for DynamicManagedValue

fn from(value: DynamicManagedGc) -> Self

Converts to this type from the input type.

impl Send for DynamicManagedGc

impl Sync for DynamicManagedGc

impl TryFrom<DynamicManagedValue> for DynamicManagedGc

type Error = ()

The type returned in the event of a conversion error.

fn try_from(value: DynamicManagedValue) -> Result<Self, Self::Error>

Performs the conversion.