- Generated by
1.9.3
|
Wasmtime
|
Wasmtime's C API. More...
#include <wasi.h>#include <wasmtime/conf.h>#include <wasmtime/config.h>#include <wasmtime/engine.h>#include <wasmtime/error.h>#include <wasmtime/extern.h>#include <wasmtime/func.h>#include <wasmtime/global.h>#include <wasmtime/instance.h>#include <wasmtime/linker.h>#include <wasmtime/memory.h>#include <wasmtime/module.h>#include <wasmtime/profiling.h>#include <wasmtime/sharedmemory.h>#include <wasmtime/store.h>#include <wasmtime/table.h>#include <wasmtime/trap.h>#include <wasmtime/val.h>#include <wasmtime/async.h>Go to the source code of this file.
Functions | |
| wasmtime_error_t * | wasmtime_wat2wasm (const char *wat, size_t wat_len, wasm_byte_vec_t *ret) |
| Converts from the text format of WebAssembly to the binary format. More... | |
Wasmtime's C API.
This file is the central inclusion point for Wasmtime's C API. There are a number of sub-header files but this file includes them all. The C API is based on wasm.h but there are many Wasmtime-specific APIs which are tailored to Wasmtime's implementation.
The wasm_config_t and wasm_engine_t types are used from wasm.h. Additionally all type-level information (like wasm_functype_t) is also used from wasm.h. Otherwise, though, all wasm objects (like wasmtime_store_t or wasmtime_func_t) are used from this header file.
The multithreading story of the C API very closely follows the multithreading story of the Rust API for Wasmtime. All objects are safe to send to other threads so long as user-specific data is also safe to send to other threads. Functions are safe to call from any thread but some functions cannot be called concurrently. For example, functions which correspond to &T in Rust can be called concurrently with any other methods that take &T. Functions that take &mut T in Rust, however, cannot be called concurrently with any other function (but can still be invoked on any thread).
This generally equates to mutation of internal state. Functions which don't mutate anything, such as learning type information through wasmtime_func_type, can be called concurrently. Functions which do require mutation, for example wasmtime_func_call, cannot be called concurrently. This is conveyed in the C API with either const wasmtime_context_t* (concurrency is ok as it's read-only) or wasmtime_context_t* (concurrency is not ok, mutation may happen).
When in doubt assume that functions cannot be called concurrently with aliasing objects.
The C API for Wasmtime is intended to be a relatively thin layer over the Rust API for Wasmtime. Rust has much more strict rules about aliasing than C does, and the Rust API for Wasmtime is designed around these rules to be used safely. These same rules must be upheld when using the C API of Wasmtime.
The main consequence of this is that the wasmtime_context_t pointer into the wasmtime_store_t must be carefully used. Since the context is an internal pointer into the store it must be used carefully to ensure you're not doing something that Rust would otherwise forbid at compile time. A wasmtime_context_t can only be used when you would otherwise have been provided access to it. For example in a host function created with wasmtime_func_new you can use wasmtime_context_t in the host function callback. This is because an argument, a wasmtime_caller_t, provides access to wasmtime_context_t.
A foundational construct in this API is the wasmtime_store_t. A store is a collection of host-provided objects and instantiated wasm modules. Stores are often treated as a "single unit" and items within a store are all allowed to reference one another. References across stores cannot currently be created. For example you cannot pass a function from one store into another store.
A store is not intended to be a global long-lived object. Stores provide no means of internal garbage collections of wasm objects (such as instances), meaning that no memory from a store will be deallocated until you call wasmtime_store_delete. If you're working with a web server, for example, then it's recommended to think of a store as a "one per request" sort of construct. Globally you'd have one wasm_engine_t and a cache of wasmtime_module_t instances compiled into that engine. Each request would create a new wasmtime_store_t and then instantiate a wasmtime_module_t into the store. This process of creating a store and instantiating a module is expected to be quite fast. When the request is finished you'd delete the wasmtime_store_t keeping memory usage reasonable for the lifetime of the server.
| wasmtime_error_t * wasmtime_wat2wasm | ( | const char * | wat, |
| size_t | wat_len, | ||
| wasm_byte_vec_t * | ret | ||
| ) |
Converts from the text format of WebAssembly to the binary format.
| wat | this it the input pointer with the WebAssembly Text Format inside of it. This will be parsed and converted to the binary format. |
| wat_len | this it the length of wat, in bytes. |
| ret | if the conversion is successful, this byte vector is filled in with the WebAssembly binary format. |
NULL. If parsing fails then ret isn't touched.This function does not take ownership of wat, and the caller is expected to deallocate the returned wasmtime_error_t and wasm_byte_vec_t.
1.9.3