wasmtime 9.0.4 → 10.0.1

data/ext/cargo-vendor/wasmtime-9.0.4/src/lib.rs

@@ -1,481 +0,0 @@
-//! Wasmtime's embedding API
-//!
-//! Wasmtime is a WebAssembly engine for JIT-complied or ahead-of-time compiled
-//! WebAssembly modules. More information about the Wasmtime project as a whole
-//! can be found [in the documentation book](https://docs.wasmtime.dev) whereas
-//! this documentation mostly focuses on the API reference of the `wasmtime`
-//! crate itself.
-//!
-//! This crate contains an API used to interact with WebAssembly modules. For
-//! example you can compile modules, instantiate them, call them, etc. As an
-//! embedder of WebAssembly you can also provide WebAssembly modules
-//! functionality from the host by creating host-defined functions, memories,
-//! globals, etc, which can do things that WebAssembly cannot (such as print to
-//! the screen).
-//!
-//! The `wasmtime` crate has similar concepts to the
-//! the [JS WebAssembly
-//! API](https://developer.mozilla.org/en-US/docs/WebAssembly) as well as the
-//! [proposed C API](https://github.com/webassembly/wasm-c-api), but the Rust
-//! API is designed for efficiency, ergonomics, and expressivity in Rust. As
-//! with all other Rust code you're guaranteed that programs will be safe (not
-//! have undefined behavior or segfault) so long as you don't use `unsafe` in
-//! your own program. With `wasmtime` you can easily and conveniently embed a
-//! WebAssembly runtime with confidence that the WebAssembly is safely
-//! sandboxed.
-//!
-//! An example of using Wasmtime looks like:
-//!
-//! ```
-//! use wasmtime::*;
-//!
-//! fn main() -> wasmtime::Result<()> {
-//!     // Modules can be compiled through either the text or binary format
-//!     let engine = Engine::default();
-//!     let wat = r#"
-//!         (module
-//!             (import "host" "host_func" (func $host_hello (param i32)))
-//!
-//!             (func (export "hello")
-//!                 i32.const 3
-//!                 call $host_hello)
-//!         )
-//!     "#;
-//!     let module = Module::new(&engine, wat)?;
-//!
-//!     // All wasm objects operate within the context of a "store". Each
-//!     // `Store` has a type parameter to store host-specific data, which in
-//!     // this case we're using `4` for.
-//!     let mut store = Store::new(&engine, 4);
-//!     let host_func = Func::wrap(&mut store, |caller: Caller<'_, u32>, param: i32| {
-//!         println!("Got {} from WebAssembly", param);
-//!         println!("my host state is: {}", caller.data());
-//!     });
-//!
-//!     // Instantiation of a module requires specifying its imports and then
-//!     // afterwards we can fetch exports by name, as well as asserting the
-//!     // type signature of the function with `get_typed_func`.
-//!     let instance = Instance::new(&mut store, &module, &[host_func.into()])?;
-//!     let hello = instance.get_typed_func::<(), ()>(&mut store, "hello")?;
-//!
-//!     // And finally we can call the wasm!
-//!     hello.call(&mut store, ())?;
-//!
-//!     Ok(())
-//! }
-//! ```
-//!
-//! ## Core Concepts
-//!
-//! There are a number of core types and concepts that are important to be aware
-//! of when using the `wasmtime` crate:
-//!
-//! * [`Engine`] - a global compilation environment for WebAssembly. An
-//!   [`Engine`] is an object that can be shared concurrently across threads and
-//!   is created with a [`Config`] to tweak various settings. Compilation of any
-//!   WebAssembly requires first configuring and creating an [`Engine`].
-//!
-//! * [`Module`] - a compiled WebAssembly module. This structure represents
-//!   in-memory JIT code which is ready to execute after being instantiated.
-//!   It's often important to cache instances of a [`Module`] because creation
-//!   (compilation) can be expensive. Note that [`Module`] is safe to share
-//!   across threads, and can be created from a WebAssembly binary and an
-//!   [`Engine`] with [`Module::new`]. Caching can either happen with
-//!   [`Engine::precompile_module`] or [`Module::serialize`], feeding those
-//!   bytes back into [`Module::deserialize`].
-//!
-//! * [`Store`] - container for all information related to WebAssembly objects
-//!   such as functions, instances, memories, etc. A [`Store<T>`][`Store`]
-//!   allows customization of the `T` to store arbitrary host data within a
-//!   [`Store`]. This host data can be accessed through host functions via the
-//!   [`Caller`] function parameter in host-defined functions. A [`Store`] is
-//!   required for all WebAssembly operations, such as calling a wasm function.
-//!   The [`Store`] is passed in as a "context" to methods like [`Func::call`].
-//!   Dropping a [`Store`] will deallocate all memory associated with
-//!   WebAssembly objects within the [`Store`].
-//!
-//! * [`Instance`] - an instantiated WebAssembly module. An instance is where
-//!   you can actually acquire a [`Func`] from, for example, to call.
-//!
-//! * [`Func`] - a WebAssembly (or host) function. This can be acquired as the
-//!   export of an [`Instance`] to call WebAssembly functions, or it can be
-//!   created via functions like [`Func::wrap`] to wrap host-defined
-//!   functionality and give it to WebAssembly.
-//!
-//! * [`Table`], [`Global`], [`Memory`] - other WebAssembly objects which can
-//!   either be defined on the host or in wasm itself (via instances). These all
-//!   have various ways of being interacted with like [`Func`].
-//!
-//! All "store-connected" types such as [`Func`], [`Memory`], etc, require the
-//! store to be passed in as a context to each method. Methods in wasmtime
-//! frequently have their first parameter as either [`impl
-//! AsContext`][`AsContext`] or [`impl AsContextMut`][`AsContextMut`]. These
-//! traits are implemented for a variety of types, allowing you to, for example,
-//! pass the following types into methods:
-//!
-//! * `&Store<T>`
-//! * `&mut Store<T>`
-//! * `&Caller<'_, T>`
-//! * `&mut Caller<'_, T>`
-//! * `StoreContext<'_, T>`
-//! * `StoreContextMut<'_, T>`
-//!
-//! A [`Store`] is the sole owner of all WebAssembly internals. Types like
-//! [`Func`] point within the [`Store`] and require the [`Store`] to be provided
-//! to actually access the internals of the WebAssembly function, for instance.
-//!
-//! ## Linking
-//!
-//! WebAssembly modules almost always require functionality from the host to
-//! perform I/O-like tasks. They might refer to quite a few pieces of host
-//! functionality, WASI, or maybe even a number of other wasm modules. To assist
-//! with managing this a [`Linker`] type is provided to instantiate modules.
-//!
-//! A [`Linker`] performs name-based resolution of the imports of a WebAssembly
-//! module so the [`Linker::instantiate`] method does not take an `imports`
-//! argument like [`Instance::new`] does. Methods like [`Linker::define`] or
-//! [`Linker::func_wrap`] can be used to define names within a [`Linker`] to
-//! later be used for instantiation.
-//!
-//! For example we can reimplement the above example with a `Linker`:
-//!
-//! ```
-//! use wasmtime::*;
-//!
-//! fn main() -> wasmtime::Result<()> {
-//!     let engine = Engine::default();
-//!     let wat = r#"
-//!         (module
-//!             (import "host" "host_func" (func $host_hello (param i32)))
-//!
-//!             (func (export "hello")
-//!                 i32.const 3
-//!                 call $host_hello)
-//!         )
-//!     "#;
-//!     let module = Module::new(&engine, wat)?;
-//!
-//!     // Create a `Linker` and define our host function in it:
-//!     let mut linker = Linker::new(&engine);
-//!     linker.func_wrap("host", "host_func", |caller: Caller<'_, u32>, param: i32| {
-//!         println!("Got {} from WebAssembly", param);
-//!         println!("my host state is: {}", caller.data());
-//!     })?;
-//!
-//!     // Use the `linker` to instantiate the module, which will automatically
-//!     // resolve the imports of the module using name-based resolution.
-//!     let mut store = Store::new(&engine, 0);
-//!     let instance = linker.instantiate(&mut store, &module)?;
-//!     let hello = instance.get_typed_func::<(), ()>(&mut store, "hello")?;
-//!     hello.call(&mut store, ())?;
-//!
-//!     Ok(())
-//! }
-//! ```
-//!
-//! The [`Linker`] type also transparently handles Commands and Reactors
-//! as defined by WASI.
-//!
-//! ## Example Architecture
-//!
-//! To better understand how Wasmtime types interact with each other let's walk
-//! through, at a high-level, an example of how you might use WebAssembly. In
-//! our use case let's say we have a web server where we'd like to run some
-//! custom WebAssembly on each request. To ensure requests are entirely isolated
-//! from each other, though, we'll be creating a new [`Store`] for each
-//! request.
-//!
-//! When the server starts, we'll start off by creating an [`Engine`] (and maybe
-//! tweaking [`Config`] settings if necessary). This [`Engine`] will be the only
-//! engine for the lifetime of the server itself. Next, we can compile our
-//! WebAssembly. You'd create a [`Module`] through the [`Module::new`] API.
-//! This will generate JIT code and perform expensive compilation tasks
-//! up-front. Finally the last step of initialization would be to create a
-//! [`Linker`] which will later be used to instantiate modules, adding
-//! functionality like WASI to the linker too.
-//!
-//! After that setup, the server starts up as usual and is ready to receive
-//! requests. Upon receiving a request you'd then create a [`Store`] with
-//! [`Store::new`] referring to the original [`Engine`]. Using your [`Module`]
-//! and [`Linker`] from before you'd then call [`Linker::instantiate`] to
-//! instantiate our module for the request. Both of these operations are
-//! designed to be as cheap as possible.
-//!
-//! With an [`Instance`] you can then invoke various exports and interact with
-//! the WebAssembly module. Once the request is finished, the [`Store`]
-//! is dropped and everything will be deallocated. Note that if the same
-//! [`Store`] were used for every request then that would have all requests
-//! sharing resources and nothing would ever get deallocated, causing memory
-//! usage to baloon and would achive less isolation between requests.
-//!
-//! ## WASI
-//!
-//! The `wasmtime` crate does not natively provide support for WASI, but you can
-//! use the [`wasmtime-wasi`] crate for that purpose. With [`wasmtime-wasi`] all
-//! WASI functions can be added to a [`Linker`] and then used to instantiate
-//! WASI-using modules. For more information see the [WASI example in the
-//! documentation](https://docs.wasmtime.dev/examples-rust-wasi.html).
-//!
-//! [`wasmtime-wasi`]: https://crates.io/crates/wasmtime-wasi
-//!
-//! ## Cross-store usage of items
-//!
-//! In `wasmtime` wasm items such as [`Global`] and [`Memory`] "belong" to a
-//! [`Store`]. The store they belong to is the one they were created with
-//! (passed in as a parameter) or instantiated with. This store is the only
-//! store that can be used to interact with wasm items after they're created.
-//!
-//! The `wasmtime` crate will panic if the [`Store`] argument passed in to these
-//! operations is incorrect. In other words it's considered a programmer error
-//! rather than a recoverable error for the wrong [`Store`] to be used when
-//! calling APIs.
-//!
-//! ## Crate Features
-//!
-//! The `wasmtime` crate comes with a number of compile-time features that can
-//! be used to customize what features it supports. Some of these features are
-//! just internal details, but some affect the public API of the `wasmtime`
-//! crate. Be sure to check the API you're using to see if any crate features
-//! are enabled.
-//!
-//! * `cranelift` - Enabled by default, this features enables using Cranelift at
-//!   runtime to compile a WebAssembly module to native code. This feature is
-//!   required to process and compile new WebAssembly modules. If this feature
-//!   is disabled then the only way to create a [`Module`] is to use the
-//!   [`Module::deserialize`] function with a precompiled artifact (typically
-//!   compiled with the same version of Wasmtime, just somewhere else).
-//!
-//! * `cache` - Enabled by default, this feature adds support for wasmtime to
-//!   perform internal caching of modules in a global location. This must still
-//!   be enabled explicitly through [`Config::cache_config_load`] or
-//!   [`Config::cache_config_load_default`].
-//!
-//! * `wat` - Enabled by default, this feature adds support for accepting the
-//!   text format of WebAssembly in [`Module::new`]. The text format will be
-//!   automatically recognized and translated to binary when compiling a
-//!   module.
-//!
-//! * `parallel-compilation` - Enabled by default, this feature enables support
-//!   for compiling functions of a module in parallel with `rayon`.
-//!
-//! * `async` - Enabled by default, this feature enables APIs and runtime
-//!   support for defining asynchronous host functions and calling WebAssembly
-//!   asynchronously.
-//!
-//! * `jitdump` - Enabled by default, this feature compiles in support for the
-//!   jitdump runtime profiling format. The profiler can be selected with
-//!   [`Config::profiler`].
-//!
-//! * `vtune` - Enabled by default, this feature compiles in support for VTune
-//!   profiling of JIT code.
-//!
-//! * `all-arch` - Not enabled by default. This feature compiles in support for
-//!   all architectures for both the JIT compiler and the `wasmtime compile` CLI
-//!   command.
-//!
-//! * `pooling-allocator` - Enabled by default, this feature adds support for
-//!   the pooling allocation strategy enabled via
-//!   [`Config::allocation_strategy`]. The pooling allocator can enable more
-//!   efficient reuse of resources for high-concurrency and
-//!   high-instantiation-count scenarios.
-//!
-//! * `memory-init-cow` - Enabled by default, this feature builds in support
-//!   for, on supported platforms, initializing wasm linear memories with
-//!   copy-on-write heap mappings. This makes instantiation much faster by
-//!   `mmap`-ing the initial memory image into place instead of copying memory
-//!   into place, allowing sharing pages that end up only getting read. Note
-//!   that this is simply compile-time support and this must also be enabled at
-//!   run-time via [`Config::memory_init_cow`] (which is also enabled by
-//!   default).
-//!
-//! ## Examples
-//!
-//! In addition to the examples below be sure to check out the [online embedding
-//! documentation][rustdocs] as well as the [online list of examples][examples]
-//!
-//! [rustdocs]: https://bytecodealliance.github.io/wasmtime/lang-rust.html
-//! [examples]: https://bytecodealliance.github.io/wasmtime/examples-rust-embed.html
-//!
-//! An example of using WASI looks like:
-//!
-//! ```no_run
-//! # use wasmtime::*;
-//! use wasmtime_wasi::sync::WasiCtxBuilder;
-//!
-//! # fn main() -> wasmtime::Result<()> {
-//! // Compile our module and create a `Linker` which has WASI functions defined
-//! // within it.
-//! let engine = Engine::default();
-//! let module = Module::from_file(&engine, "foo.wasm")?;
-//! let mut linker = Linker::new(&engine);
-//! wasmtime_wasi::add_to_linker(&mut linker, |cx| cx)?;
-//!
-//! // Configure and create a `WasiCtx`, which WASI functions need access to
-//! // through the host state of the store (which in this case is the host state
-//! // of the store)
-//! let wasi_ctx = WasiCtxBuilder::new().inherit_stdio().build();
-//! let mut store = Store::new(&engine, wasi_ctx);
-//!
-//! // Instantiate our module with the imports we've created, and run it.
-//! let instance = linker.instantiate(&mut store, &module)?;
-//! // ...
-//!
-//! # Ok(())
-//! # }
-//! ```
-//!
-//! An example of reading a string from a wasm module:
-//!
-//! ```
-//! use std::str;
-//!
-//! # use wasmtime::*;
-//! # fn main() -> wasmtime::Result<()> {
-//! let mut store = Store::default();
-//! let log_str = Func::wrap(&mut store, |mut caller: Caller<'_, ()>, ptr: i32, len: i32| {
-//!     // Use our `caller` context to learn about the memory export of the
-//!     // module which called this host function.
-//!     let mem = match caller.get_export("memory") {
-//!         Some(Extern::Memory(mem)) => mem,
-//!         _ => anyhow::bail!("failed to find host memory"),
-//!     };
-//!
-//!     // Use the `ptr` and `len` values to get a subslice of the wasm-memory
-//!     // which we'll attempt to interpret as utf-8.
-//!     let data = mem.data(&caller)
-//!         .get(ptr as u32 as usize..)
-//!         .and_then(|arr| arr.get(..len as u32 as usize));
-//!     let string = match data {
-//!         Some(data) => match str::from_utf8(data) {
-//!             Ok(s) => s,
-//!             Err(_) => anyhow::bail!("invalid utf-8"),
-//!         },
-//!         None => anyhow::bail!("pointer/length out of bounds"),
-//!     };
-//!     assert_eq!(string, "Hello, world!");
-//!     println!("{}", string);
-//!     Ok(())
-//! });
-//! let module = Module::new(
-//!     store.engine(),
-//!     r#"
-//!         (module
-//!             (import "" "" (func $log_str (param i32 i32)))
-//!             (func (export "foo")
-//!                 i32.const 4   ;; ptr
-//!                 i32.const 13  ;; len
-//!                 call $log_str)
-//!             (memory (export "memory") 1)
-//!             (data (i32.const 4) "Hello, world!"))
-//!     "#,
-//! )?;
-//! let instance = Instance::new(&mut store, &module, &[log_str.into()])?;
-//! let foo = instance.get_typed_func::<(), ()>(&mut store, "foo")?;
-//! foo.call(&mut store, ())?;
-//! # Ok(())
-//! # }
-//! ```
-
-#![deny(missing_docs)]
-#![doc(test(attr(deny(warnings))))]
-#![doc(test(attr(allow(dead_code, unused_variables, unused_mut))))]
-#![cfg_attr(nightlydoc, feature(doc_cfg))]
-#![cfg_attr(not(feature = "default"), allow(dead_code, unused_imports))]
-// Allow broken links when the default features is disabled because most of our
-// documentation is written for the "one build" of the `main` branch which has
-// most features enabled. This will present warnings in stripped-down doc builds
-// and will prevent the doc build from failing.
-#![cfg_attr(feature = "default", deny(rustdoc::broken_intra_doc_links))]
-
-#[macro_use]
-mod func;
-
-mod code;
-mod config;
-mod engine;
-mod externals;
-mod instance;
-mod limits;
-mod linker;
-mod memory;
-mod module;
-mod profiling;
-mod r#ref;
-mod signatures;
-mod store;
-mod trampoline;
-mod trap;
-mod types;
-mod values;
-
-pub use crate::config::*;
-pub use crate::engine::*;
-pub use crate::externals::*;
-pub use crate::func::*;
-pub use crate::instance::{Instance, InstancePre};
-pub use crate::limits::*;
-pub use crate::linker::*;
-pub use crate::memory::*;
-pub use crate::module::Module;
-pub use crate::profiling::GuestProfiler;
-pub use crate::r#ref::ExternRef;
-#[cfg(feature = "async")]
-pub use crate::store::CallHookHandler;
-pub use crate::store::{AsContext, AsContextMut, CallHook, Store, StoreContext, StoreContextMut};
-pub use crate::trap::*;
-pub use crate::types::*;
-pub use crate::values::*;
-
-/// A convenience wrapper for `Result<T, anyhow::Error>`.
-///
-/// This type can be used to interact with `wasmtimes`'s extensive use
-/// of `anyhow::Error` while still not directly depending on `anyhow`.
-/// This type alias is identical to `anyhow::Result`.
-pub use anyhow::{Error, Result};
-
-#[cfg(feature = "component-model")]
-pub mod component;
-
-cfg_if::cfg_if! {
-    if #[cfg(all(target_os = "macos", not(feature = "posix-signals-on-macos")))] {
-        // no extensions for macOS at this time
-    } else if #[cfg(unix)] {
-        pub mod unix;
-    } else if #[cfg(windows)] {
-        pub mod windows;
-    } else {
-        // ... unknown os!
-    }
-}
-
-fn _assert_send_sync() {
-    fn _assert<T: Send + Sync>() {}
-    fn _assert_send<T: Send>(_t: T) {}
-    _assert::<Engine>();
-    _assert::<Config>();
-    _assert::<(Func, TypedFunc<(), ()>, Global, Table, Memory)>();
-    _assert::<Instance>();
-    _assert::<Module>();
-    _assert::<Store<()>>();
-    _assert::<StoreContext<'_, ()>>();
-    _assert::<StoreContextMut<'_, ()>>();
-    _assert::<Caller<'_, ()>>();
-    _assert::<Linker<()>>();
-    _assert::<Linker<*mut u8>>();
-    _assert::<ExternRef>();
-    _assert::<InstancePre<()>>();
-    _assert::<InstancePre<*mut u8>>();
-
-    #[cfg(feature = "async")]
-    fn _call_async(s: &mut Store<()>, f: Func) {
-        _assert_send(f.call_async(&mut *s, &[], &mut []))
-    }
-    #[cfg(feature = "async")]
-    fn _typed_call_async(s: &mut Store<()>, f: TypedFunc<(), ()>) {
-        _assert_send(f.call_async(&mut *s, ()))
-    }
-    #[cfg(feature = "async")]
-    fn _instantiate_async(s: &mut Store<()>, m: &Module) {
-        _assert_send(Instance::new_async(s, m, &[]))
-    }
-}