[−][src]Struct lucet_runtime::Instance
A Lucet program, together with its dedicated memory and signal handlers.
This is the primary interface for running programs, examining return values, and accessing the WebAssembly heap.
Instance
s are never created by runtime users directly, but rather are acquired from
Region
s and often accessed through
InstanceHandle
smart pointers. This guarantees that instances
and their fields are never moved in memory, otherwise raw pointers in the metadata could be
unsafely invalidated.
An instance occupies one 4096-byte page in memory, with a layout like:
0xXXXXX000:
Instance {
.magic
.embed_ctx
... etc ...
}
// unused space
InstanceInternals {
.globals
.instruction_counter
} // last address *inside* `InstanceInternals` is 0xXXXXXFFF
0xXXXXY000: // start of next page, VMContext points here
Heap {
..
}
This layout allows modules to tightly couple to a handful of fields related to the instance,
rather than possibly requiring compiler-side changes (and recompiles) whenever Instance
changes.
It also obligates Instance
to be immediately followed by the heap, but otherwise leaves the
locations of the stack, globals, and any other data, to be implementation-defined by the
Region
that actually creates Slot
s onto which Instance
are mapped.
For information about the layout of all instance-related memory, see the documentation of
MmapRegion.
Methods
impl Instance
[src]
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 get_instruction_count(&self) -> u64
[src]
pub fn set_instruction_count(&mut self, instruction_count: u64)
[src]
Trait Implementations
impl InstanceInternal for Instance
[src]
fn alloc(&self) -> &Alloc
[src]
Get a reference to the instance's Alloc
.
fn alloc_mut(&mut self) -> &mut Alloc
[src]
Get a mutable reference to the instance's Alloc
.
fn module(&self) -> &dyn Module
[src]
Get a reference to the instance's Module
.
fn state(&self) -> &State
[src]
Get a reference to the instance's State
.
fn valid_magic(&self) -> bool
[src]
Check whether the instance magic is valid.
impl Drop for Instance
[src]
Users of Instance
must be very careful about when instances are dropped!
Typically you will not have to worry about this, as InstanceHandle will robustly handle Instance drop semantics. If an instance is dropped, and the Region it's in has already dropped, it may contain the last reference counted pointer to its Region. If so, when Instance's destructor runs, Region will be dropped, and may free or otherwise invalidate the memory that this Instance exists in, while the Instance destructor is executing.
Auto Trait Implementations
impl !Send for Instance
impl !Sync for Instance
impl Unpin for Instance
impl !UnwindSafe for Instance
impl !RefUnwindSafe for Instance
Blanket Implementations
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> From<T> for T
[src]
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>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
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> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Same<T> for T
type Output = T
Should always be Self