Struct DataStack 

pub struct DataStack { /* private fields */ }

Type-erased stack of values and registers.

Capacity is fixed at construction and rounded up to a power of two. A push that does not fit fails instead of growing the stack, so a running script cannot make the host reallocate under it. Dropping the stack unwinds everything still on it. See the module docs for the layout.

Implementations

impl DataStack

pub fn new(capacity: usize, mode: DataStackMode) -> Self

Allocates a stack of at least capacity bytes, rounded up to a power of two.

pub fn position(&self) -> usize

Returns how many bytes are used.

pub fn size(&self) -> usize

Returns the total capacity in bytes.

pub fn available(&self) -> usize

Returns how many bytes are still free.

pub fn as_bytes(&self) -> &[u8]

Returns the used part of the buffer, tags included.

pub fn visit(&self, f: impl FnMut(DataStackVisitedItem<'_>) -> bool)

Walks the stack from the top down, calling f for every item.

Stops early when f returns false, or when an item cannot be read.

pub fn push<T: Finalize + Sized + 'static>(&mut self, value: T) -> bool

Moves a value onto the stack.

Returns false without touching anything when the mode forbids values or the value does not fit.

pub unsafe fn push_raw( &mut self, layout: Layout, type_hash: TypeHash, finalizer: unsafe fn(*mut ()), data: &[u8], ) -> bool

DataStack::push for a value whose type is only known at runtime.

Safety

data must be a valid byte image of a value of the type named by type_hash, matching layout, and finalizer must be the drop function of that type. The bytes are moved, so the caller must not drop the source afterwards.

pub fn push_register<T: Finalize + 'static>(&mut self) -> Option<usize>

Reserves an empty register for values of type T and returns its index.

pub fn push_register_value<T: Finalize + 'static>( &mut self, value: T, ) -> Option<usize>

Reserves a register for T and moves value into it, returning its index.

pub unsafe fn push_register_raw( &mut self, type_hash: TypeHash, value_layout: Layout, ) -> Option<usize>

DataStack::push_register for a type only known at runtime.

Safety

value_layout must be the real layout of the type named by type_hash. A wrong layout makes every later access to that register read or write out of bounds.

pub fn push_stack(&mut self, other: Self) -> Result<(), Self>

Moves the whole content of other on top of this stack.

Gives other back untouched when it does not fit. Used to hand a batch of arguments prepared elsewhere to a call.

pub fn push_from_register( &mut self, register: &mut DataStackRegisterAccess<'_>, ) -> bool

Moves a register value onto the stack, leaving the register empty.

Returns false when the mode forbids values or the value does not fit.

pub fn pop<T: Sized + 'static>(&mut self) -> Option<T>

Moves the top value off the stack.

Returns None, leaving the stack untouched, when the top value is not a T.

pub unsafe fn pop_raw( &mut self, ) -> Option<(Layout, TypeHash, unsafe fn(*mut ()), Vec<u8>)>

DataStack::pop without knowing the type, returning the raw bytes along with the layout, type and drop function.

Safety

The returned bytes are an owned value that nothing drops for the caller. Losing them leaks, and dropping them twice is undefined. Feed them back to DataStack::push_raw or run the returned finalizer once.

pub fn drop(&mut self) -> bool

Drops the top value in place instead of returning it.

Returns false when the top of the stack is a register.

pub fn drop_register(&mut self) -> bool

Removes the topmost register, dropping its value if it holds one.

Returns false when the top of the stack is not a register.

pub fn pop_stack(&mut self, data_count: usize, capacity: Option<usize>) -> Self

Moves the top data_count values into a new stack of their own.

capacity sizes the new stack, and is raised when the values need more. Used to detach arguments for a call that runs elsewhere, for example on another thread.

pub fn pop_to_register( &mut self, register: &mut DataStackRegisterAccess<'_>, ) -> bool

Moves the top value into a register, dropping whatever the register held.

Returns false when the types do not match or the stack is empty.

pub fn store(&self) -> DataStackToken

Marks the current position, to unwind or reverse back to later.

pub fn restore(&mut self, token: DataStackToken)

Unwinds down to token, dropping every value and register above it.

This is how a scope cleans up after itself.

pub fn reverse(&mut self, token: DataStackToken)

Reverses the order of the items pushed since token.

Callers push arguments in declaration order while callees pop them in the same order, so the block has to be flipped in between. See DataStackPack::stack_push_reversed.

pub fn peek(&self) -> Option<TypeHash>

Returns the type of the top item without moving anything.

A register reports the type tag of its header, not the type it stores.

pub fn registers_count(&self) -> usize

Returns how many registers are alive.

pub fn access_register( &mut self, index: usize, ) -> Option<DataStackRegisterAccess<'_>>

Takes a handle to one register, or None when the index is unused.

pub fn access_registers_pair( &mut self, a: usize, b: usize, ) -> Option<(DataStackRegisterAccess<'_>, DataStackRegisterAccess<'_>)>

Takes handles to two different registers at once, for moving a value between them.

Returns None when the indices are equal or unused.

pub unsafe fn prevent_drop(&mut self)

Stops this stack from unwinding its content when it is dropped.

Safety

Everything still on the stack leaks unless its ownership was already handed to someone else, which is what DataStack::push_stack does.

Trait Implementations

impl Drop for DataStack

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.