[−][src]Struct substrate_wasmtime::Store
A Store
is a shared cache of information between WebAssembly modules.
Each Module
is compiled into a Store
and a Store
is associated with an
Engine
. You'll use a Store
to attach to a number of global items in
the production of various items for wasm modules.
Stores and Clone
Using clone
on a Store
is a cheap operation. It will not create an
entirely new store, but rather just a new reference to the existing object.
In other words it's a shallow copy, not a deep copy.
Stores and Default
You can create a store with default configuration settings using
Store::default()
. This will create a brand new Engine
with default
ocnfiguration (see Config
for more information).
Implementations
impl Store
[src]
pub fn new(engine: &Engine) -> Store
[src]
Creates a new store to be associated with the given Engine
.
pub fn engine(&self) -> &Engine
[src]
Returns the Engine
that this store is associated with.
pub fn same(a: &Store, b: &Store) -> bool
[src]
Returns whether the stores a
and b
refer to the same underlying
Store
.
Because the Store
type is reference counted multiple clones may point
to the same underlying storage, and this method can be used to determine
whether two stores are indeed the same.
pub fn interrupt_handle(&self) -> Result<InterruptHandle>
[src]
Creates an InterruptHandle
which can be used to interrupt the
execution of instances within this Store
.
An InterruptHandle
handle is a mechanism of ensuring that guest code
doesn't execute for too long. For example it's used to prevent wasm
programs for executing infinitely in infinite loops or recursive call
chains.
The InterruptHandle
type is sendable to other threads so you can
interact with it even while the thread with this Store
is executing
wasm code.
There's one method on an interrupt handle:
InterruptHandle::interrupt
. This method is used to generate an
interrupt and cause wasm code to exit "soon".
When are interrupts delivered?
The term "interrupt" here refers to one of two different behaviors that are interrupted in wasm:
- The head of every loop in wasm has a check to see if it's interrupted.
- The prologue of every function has a check to see if it's interrupted.
This interrupt mechanism makes no attempt to signal interrupts to native code. For example if a host function is blocked, then sending an interrupt will not interrupt that operation.
Interrupts are consumed as soon as possible when wasm itself starts executing. This means that if you interrupt wasm code then it basically guarantees that the next time wasm is executing on the target thread it will return quickly (either normally if it were already in the process of returning or with a trap from the interrupt). Once an interrupt trap is generated then an interrupt is consumed, and further execution will not be interrupted (unless another interrupt is set).
When implementing interrupts you'll want to ensure that the delivery of interrupts into wasm code is also handled in your host imports and functionality. Host functions need to either execute for bounded amounts of time or you'll need to arrange for them to be interrupted as well.
Return Value
This function returns a Result
since interrupts are not always
enabled. Interrupts are enabled via the Config::interruptable
method, and if this store's Config
hasn't been configured to enable
interrupts then an error is returned.
Examples
// Enable interruptable code via `Config` and then create an interrupt // handle which we'll use later to interrupt running code. let engine = Engine::new(Config::new().interruptable(true)); let store = Store::new(&engine); let interrupt_handle = store.interrupt_handle()?; // Compile and instantiate a small example with an infinite loop. let module = Module::new(&store, r#" (func (export "run") (loop br 0)) "#)?; let instance = Instance::new(&module, &[])?; let run = instance .get_func("run") .ok_or(anyhow::format_err!("failed to find `run` function export"))? .get0::<()>()?; // Spin up a thread to send us an interrupt in a second std::thread::spawn(move || { std::thread::sleep(std::time::Duration::from_secs(1)); interrupt_handle.interrupt(); }); let trap = run().unwrap_err(); assert!(trap.message().contains("wasm trap: interrupt"));
Trait Implementations
Auto Trait Implementations
impl !RefUnwindSafe for Store
impl Send for Store
impl Sync for Store
impl Unpin for Store
impl !UnwindSafe for Store
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> ToOwned for T where
T: Clone,
[src]
T: Clone,
type Owned = T
The resulting type after obtaining ownership.
fn to_owned(&self) -> T
[src]
fn clone_into(&self, target: &mut 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>,