[−][src]Struct lucet_runtime::InstanceHandle
A smart pointer to an Instance
that properly manages cleanup when dropped.
Instances are always stored in memory backed by a Region
; we never want to create one directly
with the Rust allocator. This type allows us to abide by that rule while also having an owned
type that cleans up the instance when we are done with it.
Since this type implements Deref
and DerefMut
to Instance
, it can usually be treated as
though it were a &mut Instance
.
Methods from Deref<Target = Instance>
pub fn run(
&mut self,
entrypoint: &str,
args: &[Val]
) -> Result<RunResult, Error>
[src]
&mut self,
entrypoint: &str,
args: &[Val]
) -> Result<RunResult, Error>
Run a function with arguments in the guest context at the given entrypoint.
// regular execution yields `Ok(UntypedRetVal)` let retval = instance.run("factorial", &[5u64.into()]).unwrap().unwrap_returned(); assert_eq!(u64::from(retval), 120u64); // runtime faults yield `Err(Error)` let result = instance.run("faulting_function", &[]); assert!(result.is_err());
Safety
This is unsafe in two ways:
-
The type of the entrypoint might not be correct. It might take a different number or different types of arguments than are provided to
args
. It might not even point to a function! We will likely add type information tolucetc
output so we can dynamically check the type in the future. -
The entrypoint is foreign code. While we may be convinced that WebAssembly compiled to native code by
lucetc
is safe, we do not have the same guarantee for the hostcalls that a guest may invoke. They might be implemented in an unsafe language, so we must treat this call as unsafe, just like any other FFI call.
For the moment, we do not mark this as unsafe
in the Rust type system, but that may change
in the future.
pub fn run_func_idx(
&mut self,
table_idx: u32,
func_idx: u32,
args: &[Val]
) -> Result<RunResult, Error>
[src]
&mut self,
table_idx: u32,
func_idx: u32,
args: &[Val]
) -> Result<RunResult, Error>
Run a function with arguments in the guest context from the WebAssembly function table.
Safety
The same safety caveats of Instance::run()
apply.
pub fn resume(&mut self) -> Result<RunResult, Error>
[src]
Resume execution of an instance that has yielded without providing a value to the guest.
This should only be used when the guest yielded with
Vmctx::yield_()
or
Vmctx::yield_val()
. Otherwise, this call will
fail with Error::InvalidArgument
.
Safety
The foreign code safety caveat of Instance::run()
applies.
pub fn resume_with_val<A>(&mut self, val: A) -> Result<RunResult, Error> where
A: 'static + Any,
[src]
A: 'static + Any,
Resume execution of an instance that has yielded, providing a value to the guest.
The type of the provided value must match the type expected by
Vmctx::yield_expecting_val()
or
Vmctx::yield_val_expecting_val()
.
The provided value will be dynamically typechecked against the type the guest expects to
receive, and if that check fails, this call will fail with Error::InvalidArgument
.
Safety
The foreign code safety caveat of Instance::run()
applies.
pub fn reset(&mut self) -> Result<(), Error>
[src]
Reset the instance's heap and global variables to their initial state.
The WebAssembly start
section will also be run, if one exists.
The embedder contexts present at instance creation or added with
Instance::insert_embed_ctx()
are not
modified by this call; it is the embedder's responsibility to clear or reset their state if
necessary.
Safety
This function runs the guest code for the WebAssembly start
section, and running any guest
code is potentially unsafe; see Instance::run()
.
pub fn grow_memory(&mut self, additional_pages: u32) -> Result<u32, Error>
[src]
Grow the guest memory by the given number of WebAssembly pages.
On success, returns the number of pages that existed before the call.
pub fn heap(&self) -> &[u8]
[src]
Return the WebAssembly heap as a slice of bytes.
pub fn heap_mut(&mut self) -> &mut [u8]
[src]
Return the WebAssembly heap as a mutable slice of bytes.
pub fn heap_u32(&self) -> &[u32]
[src]
Return the WebAssembly heap as a slice of u32
s.
pub fn heap_u32_mut(&mut self) -> &mut [u32]
[src]
Return the WebAssembly heap as a mutable slice of u32
s.
pub fn globals(&self) -> &[GlobalValue]
[src]
Return the WebAssembly globals as a slice of i64
s.
pub fn globals_mut(&mut self) -> &mut [GlobalValue]
[src]
Return the WebAssembly globals as a mutable slice of i64
s.
pub fn check_heap<T>(&self, ptr: *const T, len: usize) -> bool
[src]
Check whether a given range in the host address space overlaps with the memory that backs the instance heap.
pub fn contains_embed_ctx<T>(&self) -> bool where
T: Any,
[src]
T: Any,
Check whether a context value of a particular type exists.
pub fn get_embed_ctx<T>(&self) -> Option<Result<Ref<T>, BorrowError>> where
T: Any,
[src]
T: Any,
Get a reference to a context value of a particular type, if it exists.
pub fn get_embed_ctx_mut<T>(&self) -> Option<Result<RefMut<T>, BorrowMutError>> where
T: Any,
[src]
T: Any,
Get a mutable reference to a context value of a particular type, if it exists.
pub fn insert_embed_ctx<T>(&mut self, x: T) -> Option<T> where
T: Any,
[src]
T: Any,
Insert a context value.
If a context value of the same type already existed, it is returned.
Note: this method is intended for embedder contexts that need to be added after an
instance is created and initialized. To add a context for an instance's entire lifetime,
including the execution of its start
section, see
Region::new_instance_builder()
.
pub fn remove_embed_ctx<T>(&mut self) -> Option<T> where
T: Any,
[src]
T: Any,
Remove a context value of a particular type, returning it if it exists.
pub fn set_signal_handler<H>(&mut self, handler: H) where
H: 'static + Fn(&Instance, &Option<TrapCode>, i32, *const siginfo_t, *const c_void) -> SignalBehavior,
[src]
H: 'static + Fn(&Instance, &Option<TrapCode>, i32, *const siginfo_t, *const c_void) -> SignalBehavior,
Set the handler run when SIGBUS
, SIGFPE
, SIGILL
, or SIGSEGV
are caught by the
instance thread.
In most cases, these signals are unrecoverable for the instance that raised them, but do not affect the rest of the process.
The default signal handler returns
SignalBehavior::Default
, which yields a
runtime fault error.
The signal handler must be signal-safe.
pub fn set_fatal_handler(&mut self, handler: fn(&Instance) -> !)
[src]
Set the handler run for signals that do not arise from a known WebAssembly trap, or that involve memory outside of the current instance.
Fatal signals are not only unrecoverable for the instance that raised them, but may compromise the correctness of the rest of the process if unhandled.
The default fatal handler calls panic!()
.
pub fn set_c_fatal_handler(
&mut self,
handler: unsafe extern "C" fn(*mut Instance)
)
[src]
&mut self,
handler: unsafe extern "C" fn(*mut Instance)
)
Set the fatal handler to a C-compatible function.
This is a separate interface, because C functions can't return the !
type. Like the
regular fatal_handler
, it is not expected to return, but we cannot enforce that through
types.
When a fatal error occurs, this handler is run first, and then the regular fatal_handler
runs in case it returns.
pub fn kill_switch(&self) -> KillSwitch
[src]
pub fn is_ready(&self) -> bool
[src]
pub fn is_yielded(&self) -> bool
[src]
pub fn is_faulted(&self) -> bool
[src]
pub fn is_terminated(&self) -> bool
[src]
pub fn get_instruction_count(&self) -> u64
[src]
pub fn set_instruction_count(&mut self, instruction_count: u64)
[src]
Trait Implementations
impl Deref for InstanceHandle
[src]
type Target = Instance
The resulting type after dereferencing.
fn deref(&self) -> &<InstanceHandle as Deref>::Target
[src]
impl DerefMut for InstanceHandle
[src]
fn deref_mut(&mut self) -> &mut <InstanceHandle as Deref>::Target
[src]
impl Drop for InstanceHandle
[src]
impl Send for InstanceHandle
[src]
Auto Trait Implementations
impl !RefUnwindSafe for InstanceHandle
impl !Sync for InstanceHandle
impl Unpin for InstanceHandle
impl !UnwindSafe for InstanceHandle
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> Same<T> for T
type Output = T
Should always be Self
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,