T0b1/wasmtime
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Implement RFC 11: Redesigning Wasmtime's APIs (#2897)

Browse Source 
Implement Wasmtime's new API as designed by RFC 11. This is quite a large commit which has had lots of discussion externally, so for more information it's best to read the RFC thread and the PR thread.
This commit is contained in:
Alex Crichton
2021-06-03 09:10:53 -05:00
committed by GitHub
parent a5a28b1c5b
commit 7a1b7cdf92
233 changed files with 13349 additions and 11997 deletions
Download Patch File Download Diff File Expand all files Collapse all files

451
crates/c-api/include/doc-wasm.h
View File

File diff suppressed because it is too large Load Diff

62
crates/c-api/include/wasi.h
View File

@@ -32,9 +32,9 @@ extern "C" {
* \brief Convenience alias for #wasi_config_t
*
* \struct wasi_config_t
* \brief Opaque type used to create a #wasi_instance_t.
* \brief TODO
*
* \fn void wasi_config_delete(own wasi_config_t *);
* \fn void wasi_config_delete(wasi_config_t *);
* \brief Deletes a configuration object.
*/
WASI_DECLARE_OWN(config)
@@ -146,64 +146,6 @@ WASI_API_EXTERN void wasi_config_inherit_stderr(wasi_config_t* config);
*/
WASI_API_EXTERN bool wasi_config_preopen_dir(wasi_config_t* config, const char* path, const char* guest_path);
/**
* \typedef wasi_instance_t
* \brief Convenience alias for #wasi_instance_t
*
* \struct wasi_instance_t
* \brief Opaque type representing a WASI instance.
*
* \fn void wasi_instance_delete(own wasi_instance_t *);
* \brief Deletes an instance object.
*/
WASI_DECLARE_OWN(instance)
/**
* \brief Creates a new WASI instance from the specified configuration.
*
* \param store the store which functions will be attached to
* \param name the WASI module name that is being instantiated, currently either
* `wasi_unstable` or `wasi_snapshot_preview`.
* \param config the configuration object which has settings for how WASI APIs
* will behave.
* \param trap a location, if `NULL` is returned, that contains information
* about why instantiation failed.
*
* \return a #wasi_instance_t owned by the caller on success or `NULL` on
* failure.
*
* Note that this function takes ownership of the `config` argument whether this
* function succeeds or not. Ownership of the #wasi_instance_t and #wasm_trap_t
* are transferred to the caller.
*
* With a #wasi_instance_t you'll likely call either
* #wasmtime_linker_define_wasi or #wasi_instance_bind_import afterwards.
*/
WASI_API_EXTERN own wasi_instance_t* wasi_instance_new(
wasm_store_t* store,
const char* name,
own wasi_config_t* config,
own wasm_trap_t** trap
);
/**
* \brief Extracts a matching item for the given import from a #wasi_instance_t.
*
* \param instance the WASI instance an export is extracted from
* \param import the desired import type that is being extracted, typically
* acquired from #wasm_module_imports.
*
* \return a #wasm_extern_t which can be used to satisfy the `import`
* requested, or `NULL` if the provided `instance` cannot satisfy `import`.
*
* This function does not take ownership of its arguments, and the lifetime of
* the #wasm_extern_t is tied to the #wasi_instance_t argument.
*/
WASI_API_EXTERN const wasm_extern_t* wasi_instance_bind_import(
const wasi_instance_t* instance,
const wasm_importtype_t* import
);
#undef own
#ifdef __cplusplus

1441
crates/c-api/include/wasmtime.h
View File

File diff suppressed because it is too large Load Diff

264
crates/c-api/include/wasmtime/config.h Normal file
View File

@@ -0,0 +1,264 @@
/**
* \file wasmtime/config.h
*
* \brief Wasmtime-specific extensions to #wasm_config_t
*/
#ifndef WASMTIME_CONFIG_H
#define WASMTIME_CONFIG_H
#include <wasm.h>
#include <wasmtime/error.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* \brief Specifier for how Wasmtime will compile code, values are in
* #wasmtime_strategy_enum
*/
typedef uint8_t wasmtime_strategy_t;
/**
* \brief Different ways that Wasmtime can compile WebAssembly
*
* The default value is #WASMTIME_STRATEGY_AUTO.
*/
enum wasmtime_strategy_enum { // Strategy
/// Wasmtime will automatically determine whether to use Cranelift or
/// Lightbeam, and currently it will always pick Cranelift. This default may
/// change over time though.
WASMTIME_STRATEGY_AUTO,
/// Indicates that Cranelift will unconditionally use Cranelift to compile
/// WebAssembly code.
WASMTIME_STRATEGY_CRANELIFT,
/// Indicates that Cranelift will unconditionally use Lightbeam to compile
/// WebAssembly code. Note that Lightbeam isn't always enabled at compile
/// time, and if that's the case an error will be returned.
WASMTIME_STRATEGY_LIGHTBEAM,
};
/**
* \brief Specifier of what optimization level to use for generated JIT code.
*
* See #wasmtime_opt_level_enum for possible values.
*/
typedef uint8_t wasmtime_opt_level_t;
/**
* \brief Different ways Wasmtime can optimize generated code.
*
* The default value is #WASMTIME_OPT_LEVEL_SPEED.
*/
enum wasmtime_opt_level_enum { // OptLevel
/// Generated code will not be optimized at all.
WASMTIME_OPT_LEVEL_NONE,
/// Generated code will be optimized purely for speed.
WASMTIME_OPT_LEVEL_SPEED,
/// Generated code will be optimized, but some speed optimizations are
/// disabled if they cause the generated code to be significantly larger.
WASMTIME_OPT_LEVEL_SPEED_AND_SIZE,
};
/**
* \brief Different ways wasmtime can enable profiling JIT code.
*
* See #wasmtime_profiling_strategy_enum for possible values.
*/
typedef uint8_t wasmtime_profiling_strategy_t;
/**
* \brief Different ways to profile JIT code.
*
* The default is #WASMTIME_PROFILING_STRATEGY_NONE.
*/
enum wasmtime_profiling_strategy_enum { // ProfilingStrategy
/// No profiling is enabled at runtime.
WASMTIME_PROFILING_STRATEGY_NONE,
/// Linux's "jitdump" support in `perf` is enabled and when Wasmtime is run
/// under `perf` necessary calls will be made to profile generated JIT code.
WASMTIME_PROFILING_STRATEGY_JITDUMP,
/// Support for VTune will be enabled and the VTune runtime will be informed,
/// at runtime, about JIT code.
///
/// Note that this isn't always enabled at build time.
WASMTIME_PROFILING_STRATEGY_VTUNE,
};
#define WASMTIME_CONFIG_PROP(ret, name, ty) \
WASM_API_EXTERN ret wasmtime_config_##name##_set(wasm_config_t*, ty);
/**
* \brief Configures whether DWARF debug information is constructed at runtime
* to describe JIT code.
*
* This setting is `false` by default. When enabled it will attempt to inform
* native debuggers about DWARF debugging information for JIT code to more
* easily debug compiled WebAssembly via native debuggers. This can also
* sometimes improve the quality of output when profiling is enabled.
*/
WASMTIME_CONFIG_PROP(void, debug_info, bool)
/**
* \brief Enables WebAssembly code to be interrupted.
*
* This setting is `false` by default. When enabled it will enable getting an
* interrupt handle via #wasmtime_interrupt_handle_new which can be used to
* interrupt currently-executing WebAssembly code.
*/
WASMTIME_CONFIG_PROP(void, interruptable, bool)
/**
* \brief Whether or not fuel is enabled for generated code.
*
* This setting is `false` by default. When enabled it will enable fuel counting
* meaning that fuel will be consumed every time a wasm instruction is executed,
* and trap when reaching zero.
*/
WASMTIME_CONFIG_PROP(void, consume_fuel, bool)
/**
* \brief Configures the maximum stack size, in bytes, that JIT code can use.
*
* This setting is 2MB by default. Configuring this setting will limit the
* amount of native stack space that JIT code can use while it is executing. If
* you're hitting stack overflow you can try making this setting larger, or if
* you'd like to limit wasm programs to less stack you can also configure this.
*
* Note that this setting is not interpreted with 100% precision. Additionally
* the amount of stack space that wasm takes is always relative to the first
* invocation of wasm on the stack, so recursive calls with host frames in the
* middle will all need to fit within this setting.
*/
WASMTIME_CONFIG_PROP(void, max_wasm_stack, size_t)
/**
* \brief Configures whether the WebAssembly threading proposal is enabled.
*
* This setting is `false` by default.
*
* Note that threads are largely unimplemented in Wasmtime at this time.
*/
WASMTIME_CONFIG_PROP(void, wasm_threads, bool)
/**
* \brief Configures whether the WebAssembly reference types proposal is
* enabled.
*
* This setting is `false` by default.
*/
WASMTIME_CONFIG_PROP(void, wasm_reference_types, bool)
/**
* \brief Configures whether the WebAssembly SIMD proposal is
* enabled.
*
* This setting is `false` by default.
*/
WASMTIME_CONFIG_PROP(void, wasm_simd, bool)
/**
* \brief Configures whether the WebAssembly bulk memory proposal is
* enabled.
*
* This setting is `false` by default.
*/
WASMTIME_CONFIG_PROP(void, wasm_bulk_memory, bool)
/**
* \brief Configures whether the WebAssembly multi value proposal is
* enabled.
*
* This setting is `true` by default.
*/
WASMTIME_CONFIG_PROP(void, wasm_multi_value, bool)
/**
* \brief Configures whether the WebAssembly module linking proposal is
* enabled.
*
* This setting is `false` by default.
*/
WASMTIME_CONFIG_PROP(void, wasm_module_linking, bool)
/**
* \brief Configures how JIT code will be compiled.
*
* This setting is #WASMTIME_STRATEGY_AUTO by default.
*
* If the compilation strategy selected could not be enabled then an error is
* returned.
*/
WASMTIME_CONFIG_PROP(wasmtime_error_t*, strategy, wasmtime_strategy_t)
/**
* \brief Configures whether Cranelift's debug verifier is enabled.
*
* This setting in `false` by default.
*
* When cranelift is used for compilation this enables expensive debug checks
* within Cranelift itself to verify it's correct.
*/
WASMTIME_CONFIG_PROP(void, cranelift_debug_verifier, bool)
/**
* \brief Configures Cranelift's optimization level for JIT code.
*
* This setting in #WASMTIME_OPT_LEVEL_SPEED by default.
*/
WASMTIME_CONFIG_PROP(void, cranelift_opt_level, wasmtime_opt_level_t)
/**
* \brief Configures the profiling strategy used for JIT code.
*
* This setting in #WASMTIME_PROFILING_STRATEGY_NONE by default.
*/
WASMTIME_CONFIG_PROP(wasmtime_error_t*, profiler, wasmtime_profiling_strategy_t)
/**
* \brief Configures the maximum size for memory to be considered "static"
*
* For more information see the Rust documentation at
* https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Config.html#method.static_memory_maximum_size.
*/
WASMTIME_CONFIG_PROP(void, static_memory_maximum_size, uint64_t)
/**
* \brief Configures the guard region size for "static" memory.
*
* For more information see the Rust documentation at
* https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Config.html#method.static_memory_guard_size.
*/
WASMTIME_CONFIG_PROP(void, static_memory_guard_size, uint64_t)
/**
* \brief Configures the guard region size for "dynamic" memory.
*
* For more information see the Rust documentation at
* https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Config.html#method.dynamic_memory_guard_size.
*/
WASMTIME_CONFIG_PROP(void, dynamic_memory_guard_size, uint64_t)
/**
* \brief Enables Wasmtime's cache and loads configuration from the specified
* path.
*
* By default the Wasmtime compilation cache is disabled. The configuration path
* here can be `NULL` to use the default settings, and otherwise the argument
* here must be a file on the filesystem with TOML configuration -
* https://bytecodealliance.github.io/wasmtime/cli-cache.html.
*
* An error is returned if the cache configuration could not be loaded or if the
* cache could not be enabled.
*/
WASM_API_EXTERN wasmtime_error_t* wasmtime_config_cache_config_load(wasm_config_t*, const char*);
#ifdef __cplusplus
} // extern "C"
#endif
#endif // WASMTIME_CONFIG_H

55
crates/c-api/include/wasmtime/error.h Normal file
View File

@@ -0,0 +1,55 @@
/**
* \file wasmtime/error.h
*
* \brief Definition and accessors of #wasmtime_error_t
*/
#ifndef WASMTIME_ERROR_H
#define WASMTIME_ERROR_H
#include <wasm.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* \typedef wasmtime_error_t
* \brief Convenience alias for #wasmtime_error
*
* \struct wasmtime_error
* \brief Errors generated by Wasmtime.
* \headerfile wasmtime/error.h
*
* This opaque type represents an error that happened as part of one of the
* functions below. Errors primarily have an error message associated with them
* at this time, which you can acquire by calling #wasmtime_error_message.
*
* Errors are safe to share across threads and must be deleted with
* #wasmtime_error_delete.
*/
typedef struct wasmtime_error wasmtime_error_t;
/**
* \brief Deletes an error.
*/
WASM_API_EXTERN void wasmtime_error_delete(wasmtime_error_t *error);
/**
* \brief Returns the string description of this error.
*
* This will "render" the error to a string and then return the string
* representation of the error to the caller. The `message` argument should be
* uninitialized before this function is called and the caller is responsible
* for deallocating it with #wasm_byte_vec_delete afterwards.
*/
WASM_API_EXTERN void wasmtime_error_message(
const wasmtime_error_t *error,
wasm_name_t *message
);
#ifdef __cplusplus
} // extern "C"
#endif
#endif // WASMTIME_ERROR_H

172
crates/c-api/include/wasmtime/extern.h Normal file
View File

@@ -0,0 +1,172 @@
/**
* \file wasmtime/extern.h
*
* \brief Definition of #wasmtime_extern_t and external items.
*/
#ifndef WASMTIME_EXTERN_H
#define WASMTIME_EXTERN_H
#include <wasmtime/module.h>
#include <wasmtime/store.h>
#ifdef __cplusplus
extern "C" {
#endif
/// \brief Representation of a function in Wasmtime.
///
/// Functions are represented with a 64-bit identifying integer in Wasmtime.
/// They do not have any destructor associated with them. Functions cannot
/// interoperate between #wasmtime_store_t instances and if the wrong function
/// is passed to the wrong store then it may trigger an assertion to abort the
/// process.
typedef struct wasmtime_func {
/// Internal identifier of what store this belongs to, never zero.
uint64_t store_id;
/// Internal index within the store.
size_t index;
} wasmtime_func_t;
/// \brief Representation of a table in Wasmtime.
///
/// Tables are represented with a 64-bit identifying integer in Wasmtime.
/// They do not have any destructor associated with them. Tables cannot
/// interoperate between #wasmtime_store_t instances and if the wrong table
/// is passed to the wrong store then it may trigger an assertion to abort the
/// process.
typedef struct wasmtime_table {
/// Internal identifier of what store this belongs to, never zero.
uint64_t store_id;
/// Internal index within the store.
size_t index;
} wasmtime_table_t;
/// \brief Representation of a memory in Wasmtime.
///
/// Memories are represented with a 64-bit identifying integer in Wasmtime.
/// They do not have any destructor associated with them. Memories cannot
/// interoperate between #wasmtime_store_t instances and if the wrong memory
/// is passed to the wrong store then it may trigger an assertion to abort the
/// process.
typedef struct wasmtime_memory {
/// Internal identifier of what store this belongs to, never zero.
uint64_t store_id;
/// Internal index within the store.
size_t index;
} wasmtime_memory_t;
/// \brief Representation of a instance in Wasmtime.
///
/// Instances are represented with a 64-bit identifying integer in Wasmtime.
/// They do not have any destructor associated with them. Instances cannot
/// interoperate between #wasmtime_store_t instances and if the wrong instance
/// is passed to the wrong store then it may trigger an assertion to abort the
/// process.
typedef struct wasmtime_instance {
/// Internal identifier of what store this belongs to, never zero.
uint64_t store_id;
/// Internal index within the store.
size_t index;
} wasmtime_instance_t;
/// \brief Representation of a global in Wasmtime.
///
/// Globals are represented with a 64-bit identifying integer in Wasmtime.
/// They do not have any destructor associated with them. Globals cannot
/// interoperate between #wasmtime_store_t instances and if the wrong global
/// is passed to the wrong store then it may trigger an assertion to abort the
/// process.
typedef struct wasmtime_global {
/// Internal identifier of what store this belongs to, never zero.
uint64_t store_id;
/// Internal index within the store.
size_t index;
} wasmtime_global_t;
/// \brief Disciminant of #wasmtime_extern_t
typedef uint8_t wasmtime_extern_kind_t;
/// \brief Value of #wasmtime_extern_kind_t meaning that #wasmtime_extern_t is a
/// function
#define WASMTIME_EXTERN_FUNC 0
/// \brief Value of #wasmtime_extern_kind_t meaning that #wasmtime_extern_t is a
/// global
#define WASMTIME_EXTERN_GLOBAL 1
/// \brief Value of #wasmtime_extern_kind_t meaning that #wasmtime_extern_t is a
/// table
#define WASMTIME_EXTERN_TABLE 2
/// \brief Value of #wasmtime_extern_kind_t meaning that #wasmtime_extern_t is a
/// memory
#define WASMTIME_EXTERN_MEMORY 3
/// \brief Value of #wasmtime_extern_kind_t meaning that #wasmtime_extern_t is
/// an instance
#define WASMTIME_EXTERN_INSTANCE 4
/// \brief Value of #wasmtime_extern_kind_t meaning that #wasmtime_extern_t is
/// a module
#define WASMTIME_EXTERN_MODULE 5
/**
* \typedef wasmtime_extern_union_t
* \brief Convenience alias for #wasmtime_extern_union
*
* \union wasmtime_extern_union
* \brief Container for different kinds of extern items.
*
* This type is contained in #wasmtime_extern_t and contains the payload for the
* various kinds of items an extern wasm item can be.
*/
typedef union wasmtime_extern_union {
/// Field used if #wasmtime_extern_t::kind is #WASMTIME_EXTERN_FUNC
wasmtime_func_t func;
/// Field used if #wasmtime_extern_t::kind is #WASMTIME_EXTERN_GLOBAL
wasmtime_global_t global;
/// Field used if #wasmtime_extern_t::kind is #WASMTIME_EXTERN_TABLE
wasmtime_table_t table;
/// Field used if #wasmtime_extern_t::kind is #WASMTIME_EXTERN_MEMORY
wasmtime_memory_t memory;
/// Field used if #wasmtime_extern_t::kind is #WASMTIME_EXTERN_INSTANCE
wasmtime_instance_t instance;
/// Field used if #wasmtime_extern_t::kind is #WASMTIME_EXTERN_MODULE
///
/// Note that this may be an owned pointer depending on the ownership of the
/// #wasmtime_extern_t container value.
wasmtime_module_t *module;
} wasmtime_extern_union_t;
/**
* \typedef wasmtime_extern_t
* \brief Convenience alias for #wasmtime_extern_t
*
* \union wasmtime_extern
* \brief Container for different kinds of extern items.
*
* Note that this structure may contain an owned value, namely
* #wasmtime_module_t, depending on the context in which this is used. APIs
* which consume a #wasmtime_extern_t do not take ownership, but APIs that
* return #wasmtime_extern_t require that #wasmtime_extern_delete is called to
* deallocate the value.
*/
typedef struct wasmtime_extern {
/// Discriminant of which field of #of is valid.
wasmtime_extern_kind_t kind;
/// Container for the extern item's value.
wasmtime_extern_union_t of;
} wasmtime_extern_t;
/// \brief Deletes a #wasmtime_extern_t.
void wasmtime_extern_delete(wasmtime_extern_t *val);
/// \brief Returns the type of the #wasmtime_extern_t defined within the given
/// store.
///
/// Does not take ownership of `context` or `val`, but the returned
/// #wasm_externtype_t is an owned value that needs to be deleted.
wasm_externtype_t *wasmtime_extern_type(wasmtime_context_t *context, wasmtime_extern_t *val);
#ifdef __cplusplus
} // extern "C"
#endif
#endif // WASMTIME_EXTERN_H

179
crates/c-api/include/wasmtime/func.h Normal file
View File

@@ -0,0 +1,179 @@
/**
* \file wasmtime/func.h
*
* Wasmtime definitions of how to interact with host and wasm functions.
*/
#ifndef WASMTIME_FUNC_H
#define WASMTIME_FUNC_H
#include <wasm.h>
#include <wasmtime/val.h>
#include <wasmtime/store.h>
#include <wasmtime/extern.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* \typedef wasmtime_caller_t
* \brief Alias to #wasmtime_caller
*
* \brief Structure used to learn about the caller of a host-defined function.
* \struct wasmtime_caller
*
* This structure is an argument to #wasmtime_func_callback_t. The purpose
* of this structure is acquire a #wasmtime_context_t pointer to interact with
* objects, but it can also be used for inspect the state of the caller (such as
* getting memories and functions) with #wasmtime_caller_export_get.
*
* This object is never owned and does not need to be deleted.
*/
typedef struct wasmtime_caller wasmtime_caller_t;
/**
* \brief Callback signature for #wasmtime_func_new.
*
* This is the function signature for host functions that can be made accessible
* to WebAssembly. The arguments to this function are:
*
* \param env user-provided argument passed to #wasmtime_func_new
* \param caller a temporary object that can only be used during this function
* call. Used to acquire #wasmtime_context_t or caller's state
* \param args the arguments provided to this function invocation
* \param nargs how many arguments are provided
* \param results where to write the results of this function
* \param nresults how many results must be produced
*
* Callbacks are guaranteed to get called with the right types of arguments, but
* they must produce the correct number and types of results. Failure to do so
* will cause traps to get raised on the wasm side.
*
* This callback can optionally return a #wasm_trap_t indicating that a trap
* should be raised in WebAssembly. It's expected that in this case the caller
* relinquishes ownership of the trap and it is passed back to the engine.
*/
typedef wasm_trap_t* (*wasmtime_func_callback_t)(
void *env,
wasmtime_caller_t* caller,
const wasmtime_val_t *args,
size_t nargs,
wasmtime_val_t *results,
size_t nresults);
/**
* \brief Creates a new host-defined function.
*
* Inserts a host-defined function into the `store` provided which can be used
* to then instantiate a module with or define within a #wasmtime_linker_t.
*
* \param store the store in which to create the function
* \param type the wasm type of the function that's being created
* \param callback the host-defined callback to invoke
* \param env host-specific data passed to the callback invocation, can be
* `NULL`
* \param finalizer optional finalizer for `env`, can be `NULL`
* \param ret the #wasmtime_func_t return value to be filled in.
*
* The returned function can only be used with the specified `store`.
*/
WASM_API_EXTERN void wasmtime_func_new(
wasmtime_context_t *store,
const wasm_functype_t* type,
wasmtime_func_callback_t callback,
void *env,
void (*finalizer)(void*),
wasmtime_func_t *ret
);
/**
* \brief Returns the type of the function specified
*
* The returned #wasm_functype_t is owned by the caller.
*/
WASM_API_EXTERN wasm_functype_t* wasmtime_func_type(
const wasmtime_context_t *store,
const wasmtime_func_t *func
);
/**
* \brief Call a WebAssembly function.
*
* This function is used to invoke a function defined within a store. For
* example this might be used after extracting a function from a
* #wasmtime_instance_t.
*
* \param store the store which owns `func`
* \param func the function to call
* \param args the arguments to the function call
* \param nargs the number of arguments provided
* \param results where to write the results of the function call
* \param nresults the number of results expected
* \param trap where to store a trap, if one happens.
*
* There are three possible return states from this function:
*
* 1. The returned error is non-null. This means `results`
* wasn't written to and `trap` will have `NULL` written to it. This state
* means that programmer error happened when calling the function, for
* example when the size of the arguments/results was wrong, the types of the
* arguments were wrong, or arguments may come from the wrong store.
* 2. The trap pointer is filled in. This means the returned error is `NULL` and
* `results` was not written to. This state means that the function was
* executing but hit a wasm trap while executing.
* 3. The error and trap returned are both `NULL` and `results` are written to.
* This means that the function call succeeded and the specified results were
* produced.
*
* The `trap` pointer cannot be `NULL`. The `args` and `results` pointers may be
* `NULL` if the corresponding length is zero.
*
* Does not take ownership of #wasmtime_val_t arguments. Gives ownership of
* #wasmtime_val_t results.
*/
WASM_API_EXTERN wasmtime_error_t *wasmtime_func_call(
wasmtime_context_t *store,
const wasmtime_func_t *func,
const wasmtime_val_t *args,
size_t nargs,
wasmtime_val_t *results,
size_t nresults,
wasm_trap_t **trap
);
/**
* \brief Loads a #wasmtime_extern_t from the caller's context
*
* This function will attempt to look up the export named `name` on the caller
* instance provided. If it is found then the #wasmtime_extern_t for that is
* returned, otherwise `NULL` is returned.
*
* Note that this only works for exported memories right now for WASI
* compatibility.
*
* \param caller the caller object to look up the export from
* \param name the name that's being looked up
* \param name_len the byte length of `name`
* \param item where to store the return value
*
* Returns a nonzero value if the export was found, or 0 if the export wasn't
* found. If the export wasn't found then `item` isn't written to.
*/
WASM_API_EXTERN bool wasmtime_caller_export_get(
wasmtime_caller_t *caller,
const char *name,
size_t name_len,
wasmtime_extern_t *item
);
/**
* \brief Returns the store context of the caller object.
*/
WASM_API_EXTERN wasmtime_context_t* wasmtime_caller_context(wasmtime_caller_t* caller);
#ifdef __cplusplus
} // extern "C"
#endif
#endif // WASMTIME_FUNC_H

91
crates/c-api/include/wasmtime/global.h Normal file
View File

@@ -0,0 +1,91 @@
/**
* \file wasmtime/global.h
*
* Wasmtime APIs for interacting with WebAssembly globals.
*/
#ifndef WASMTIME_GLOBAL_H
#define WASMTIME_GLOBAL_H
#include <wasm.h>
#include <wasmtime/extern.h>
#include <wasmtime/store.h>
#include <wasmtime/val.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* \brief Creates a new global value.
*
* Creates a new host-defined global value within the provided `store`
*
* \param store the store in which to create the global
* \param type the wasm type of the global being created
* \param val the initial value of the global
* \param ret a return pointer for the created global.
*
* This function may return an error if the `val` argument does not match the
* specified type of the global, or if `val` comes from a different store than
* the one provided.
*
* This function does not take ownership of any of its arguments but error is
* owned by the caller.
*/
WASM_API_EXTERN wasmtime_error_t *wasmtime_global_new(
wasmtime_context_t *store,
const wasm_globaltype_t *type,
const wasmtime_val_t *val,
wasmtime_global_t *ret
);
/**
* \brief Returns the wasm type of the specified global.
*
* The returned #wasm_globaltype_t is owned by the caller.
*/
WASM_API_EXTERN wasm_globaltype_t* wasmtime_global_type(
const wasmtime_context_t *store,
const wasmtime_global_t *global
);
/**
* \brief Get the value of the specified global.
*
* \param store the store that owns `global`
* \param global the global to get
* \param out where to store the value in this global.
*
* This function returns ownership of the contents of `out`, so
* #wasmtime_val_delete may need to be called on the value.
*/
WASM_API_EXTERN void wasmtime_global_get(
wasmtime_context_t *store,
const wasmtime_global_t *global,
wasmtime_val_t *out
);
/**
* \brief Sets a global to a new value.
*
* \param store the store that owns `global`
* \param global the global to set
* \param val the value to store in the global
*
* This function may return an error if `global` is not mutable or if `val` has
* the wrong type for `global`.
*
* THis does not take ownership of any argument but returns ownership of the error.
*/
WASM_API_EXTERN wasmtime_error_t *wasmtime_global_set(
wasmtime_context_t *store,
const wasmtime_global_t *global,
const wasmtime_val_t *val
);
#ifdef __cplusplus
} // extern "C"
#endif
#endif // WASMTIME_GLOBAL_H

158
crates/c-api/include/wasmtime/instance.h Normal file
View File

@@ -0,0 +1,158 @@
/**
* \file wasmtime/instance.h
*
* Wasmtime APIs for interacting with wasm instances.
*/
#ifndef WASMTIME_INSTANCE_H
#define WASMTIME_INSTANCE_H
#include <wasm.h>
#include <wasmtime/extern.h>
#include <wasmtime/module.h>
#include <wasmtime/store.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* \brief An opaque object representing the type of an instance.
*/
typedef struct wasmtime_instancetype wasmtime_instancetype_t;
/// \brief Deletes an instance type
WASM_API_EXTERN void wasmtime_instancetype_delete(wasmtime_instancetype_t *ty);
/**
* \brief Returns the list of exports that this instance type provides.
*
* This function does not take ownership of the provided instance type but
* ownership of `out` is passed to the caller. Note that `out` is treated as
* uninitialized when passed to this function.
*/
WASM_API_EXTERN void wasmtime_instancetype_exports(const wasmtime_instancetype_t*, wasm_exporttype_vec_t* out);
/**
* \brief Converts a #wasmtime_instancetype_t to a #wasm_externtype_t
*
* The returned value is owned by the #wasmtime_instancetype_t argument and should not
* be deleted.
*/
WASM_API_EXTERN wasm_externtype_t* wasmtime_instancetype_as_externtype(wasmtime_instancetype_t*);
/**
* \brief Attempts to convert a #wasm_externtype_t to a #wasmtime_instancetype_t
*
* The returned value is owned by the #wasmtime_instancetype_t argument and should not
* be deleted. Returns `NULL` if the provided argument is not a
* #wasmtime_instancetype_t.
*/
WASM_API_EXTERN wasmtime_instancetype_t* wasmtime_externtype_as_instancetype(wasm_externtype_t*);
/**
* \brief Instantiate a wasm module.
*
* This function will instantiate a WebAssembly module with the provided
* imports, creating a WebAssembly instance. The returned instance can then
* afterwards be inspected for exports.
*
* \param store the store in which to create the instance
* \param module the module that's being instantiated
* \param imports the imports provided to the module
* \param nimports the size of `imports`
* \param instance where to store the returned instance
* \param trap where to store the returned trap
*
* This function requires that `imports` is the same size as the imports that
* `module` has. Additionally the `imports` array must be 1:1 lined up with the
* imports of the `module` specified. This is intended to be relatively low
* level, and #wasmtime_linker_instantiate is provided for a more ergonomic
* name-based resolution API.
*
* The states of return values from this function are similar to
* #wasmtime_func_call where an error can be returned meaning something like a
* link error in this context. A trap can be returned (meaning no error or
* instance is returned), or an instance can be returned (meaning no error or
* trap is returned).
*
* Note that this function requires that all `imports` specified must be owned
* by the `store` provided as well.
*
* This function does not take ownership of any of its arguments, but all return
* values are owned by the caller.
*/
WASM_API_EXTERN wasmtime_error_t *wasmtime_instance_new(
wasmtime_context_t *store,
const wasmtime_module_t *module,
const wasmtime_extern_t* imports,
size_t nimports,
wasmtime_instance_t *instance,
wasm_trap_t **trap
);
/**
* \brief Returns the type of the specified instance.
*
* The returned type is owned by the caller.
*/
WASM_API_EXTERN wasmtime_instancetype_t *wasmtime_instance_type(
const wasmtime_context_t *store,
const wasmtime_instance_t *instance
);
/**
* \brief Get an export by name from an instance.
*
* \param store the store that owns `instance`
* \param instance the instance to lookup within
* \param name the export name to lookup
* \param name_len the byte length of `name`
* \param item where to store the returned value
*
* Returns nonzero if the export was found, and `item` is filled in. Otherwise
* returns 0.
*
* Doesn't take ownership of any arguments but does return ownership of the
* #wasmtime_extern_t.
*/
WASM_API_EXTERN bool wasmtime_instance_export_get(
wasmtime_context_t *store,
const wasmtime_instance_t *instance,
const char *name,
size_t name_len,
wasmtime_extern_t *item
);
/**
* \brief Get an export by index from an instance.
*
* \param store the store that owns `instance`
* \param instance the instance to lookup within
* \param index the index to lookup
* \param name where to store the name of the export
* \param name_len where to store the byte length of the name
* \param item where to store the export itself
*
* Returns nonzero if the export was found, and `name`, `name_len`, and `item`
* are filled in. Otherwise returns 0.
*
* Doesn't take ownership of any arguments but does return ownership of the
* #wasmtime_extern_t. The `name` pointer return value is owned by the `store`
* and must be immediately used before calling any other APIs on
* #wasmtime_context_t.
*/
WASM_API_EXTERN bool wasmtime_instance_export_nth(
wasmtime_context_t *store,
const wasmtime_instance_t *instance,
size_t index,
char **name,
size_t *name_len,
wasmtime_extern_t *item
);
#ifdef __cplusplus
} // extern "C"
#endif
#endif // WASMTIME_INSTANCE_H

239
crates/c-api/include/wasmtime/linker.h Normal file
View File

@@ -0,0 +1,239 @@
/**
* \file wasmtime/linker.h
*
* Wasmtime API for a name-based linker used to instantiate modules.
*/
#ifndef WASMTIME_LINKER_H
#define WASMTIME_LINKER_H
#include <wasm.h>
#include <wasmtime/error.h>
#include <wasmtime/store.h>
#include <wasmtime/extern.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* \typedef wasmtime_linker_t
* \brief Alias to #wasmtime_linker
*
* \struct #wasmtime_linker
* \brief Object used to conveniently link together and instantiate wasm
* modules.
*
* This type corresponds to the `wasmtime::Linker` type in Rust. This
* type is intended to make it easier to manage a set of modules that link
* together, or to make it easier to link WebAssembly modules to WASI.
*
* A #wasmtime_linker_t is a higher level way to instantiate a module than
* #wasm_instance_new since it works at the "string" level of imports rather
* than requiring 1:1 mappings.
*/
typedef struct wasmtime_linker wasmtime_linker_t;
/**
* \brief Creates a new linker for the specified engine.
*
* This function does not take ownership of the engine argument, and the caller
* is expected to delete the returned linker.
*/
WASM_API_EXTERN wasmtime_linker_t* wasmtime_linker_new(wasm_engine_t* engine);
/**
* \brief Deletes a linker
*/
WASM_API_EXTERN void wasmtime_linker_delete(wasmtime_linker_t* linker);
/**
* \brief Configures whether this linker allows later definitions to shadow
* previous definitions.
*
* By default this setting is `false`.
*/
WASM_API_EXTERN void wasmtime_linker_allow_shadowing(wasmtime_linker_t* linker, bool allow_shadowing);
/**
* \brief Defines a new item in this linker.
*
* \param linker the linker the name is being defined in.
* \param module the module name the item is defined under.
* \param module_len the byte length of `module`
* \param name the field name the item is defined under
* \param name_len the byte length of `name`
* \param item the item that is being defined in this linker.
*
* \return On success `NULL` is returned, otherwise an error is returned which
* describes why the definition failed.
*
* For more information about name resolution consult the [Rust
* documentation](https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Linker.html#name-resolution).
*/
WASM_API_EXTERN wasmtime_error_t* wasmtime_linker_define(
wasmtime_linker_t *linker,
const char *module,
size_t module_len,
const char *name,
size_t name_len,
const wasmtime_extern_t *item
);
/**
* \brief Defines WASI functions in this linker.
*
* \param linker the linker the name is being defined in.
*
* \return On success `NULL` is returned, otherwise an error is returned which
* describes why the definition failed.
*
* This function will provide WASI function names in the specified linker. Note
* that when an instance is created within a store then the store also needs to
* have its WASI settings configured with #wasmtime_context_set_wasi for WASI
* functions to work, otherwise an assert will be tripped that will abort the
* process.
*
* For more information about name resolution consult the [Rust
* documentation](https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Linker.html#name-resolution).
*/
WASM_API_EXTERN wasmtime_error_t* wasmtime_linker_define_wasi(
wasmtime_linker_t *linker
);
/**
* \brief Defines an instance under the specified name in this linker.
*
* \param linker the linker the name is being defined in.
* \param store the store that owns `instance`
* \param name the module name to define `instance` under.
* \param name_len the byte length of `name`
* \param instance a previously-created instance.
*
* \return On success `NULL` is returned, otherwise an error is returned which
* describes why the definition failed.
*
* This function will take all of the exports of the `instance` provided and
* defined them under a module called `name` with a field name as the export's
* own name.
*
* For more information about name resolution consult the [Rust
* documentation](https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Linker.html#name-resolution).
*/
WASM_API_EXTERN wasmtime_error_t* wasmtime_linker_define_instance(
wasmtime_linker_t *linker,
wasmtime_context_t *store,
const char *name,
size_t name_len,
const wasmtime_instance_t *instance
);
/**
* \brief Instantiates a #wasm_module_t with the items defined in this linker.
*
* \param linker the linker used to instantiate the provided module.
* \param store the store that is used to instantiate within
* \param module the module that is being instantiated.
* \param instance the returned instance, if successful.
* \param trap a trap returned, if the start function traps.
*
* \return One of three things can happen as a result of this function. First
* the module could be successfully instantiated and returned through
* `instance`, meaning the return value and `trap` are both set to `NULL`.
* Second the start function may trap, meaning the return value and `instance`
* are set to `NULL` and `trap` describes the trap that happens. Finally
* instantiation may fail for another reason, in which case an error is returned
* and `trap` and `instance` are set to `NULL`.
*
* This function will attempt to satisfy all of the imports of the `module`
* provided with items previously defined in this linker. If any name isn't
* defined in the linker than an error is returned. (or if the previously
* defined item is of the wrong type).
*/
WASM_API_EXTERN wasmtime_error_t* wasmtime_linker_instantiate(
const wasmtime_linker_t *linker,
wasmtime_context_t *store,
const wasmtime_module_t *module,
wasmtime_instance_t *instance,
wasm_trap_t **trap
);
/**
* \brief Defines automatic instantiations of a #wasm_module_t in this linker.
*
* \param linker the linker the module is being added to
* \param store the store that is used to instantiate `module`
* \param name the name of the module within the linker
* \param name_len the byte length of `name`
* \param module the module that's being instantiated
*
* \return An error if the module could not be instantiated or added or `NULL`
* on success.
*
* This function automatically handles [Commands and
* Reactors](https://github.com/WebAssembly/WASI/blob/master/design/application-abi.md#current-unstable-abi)
* instantiation and initialization.
*
* For more information see the [Rust
* documentation](https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Linker.html#method.module).
*/
WASM_API_EXTERN wasmtime_error_t* wasmtime_linker_module(
wasmtime_linker_t *linker,
wasmtime_context_t *store,
const char *name,
size_t name_len,
const wasmtime_module_t *module
);
/**
* \brief Acquires the "default export" of the named module in this linker.
*
* \param linker the linker to load from
* \param store the store to load a function into
* \param name the name of the module to get the default export for
* \param name_len the byte length of `name`
* \param func where to store the extracted default function.
*
* \return An error is returned if the default export could not be found, or
* `NULL` is returned and `func` is filled in otherwise.
*
* For more information see the [Rust
* documentation](https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Linker.html#method.get_default).
*/
WASM_API_EXTERN wasmtime_error_t* wasmtime_linker_get_default(
const wasmtime_linker_t *linker,
wasmtime_context_t *store,
const char *name,
size_t name_len,
wasmtime_func_t *func
);
/**
* \brief Loads an item by name from this linker.
*
* \param linker the linker to load from
* \param store the store to load the item into
* \param module the name of the module to get
* \param module_len the byte length of `module`
* \param name the name of the field to get
* \param name_len the byte length of `name`
* \param item where to store the extracted item
*
* \return A nonzero value if the item is defined, in which case `item` is also
* filled in. Otherwise zero is returned.
*/
WASM_API_EXTERN bool wasmtime_linker_get(
const wasmtime_linker_t *linker,
wasmtime_context_t *store,
const char *module,
size_t module_len,
const char *name,
size_t name_len,
wasmtime_extern_t *item
);
#ifdef __cplusplus
} // extern "C"
#endif
#endif // WASMTIME_LINKER_H

90
crates/c-api/include/wasmtime/memory.h Normal file
View File

@@ -0,0 +1,90 @@
/**
* \file wasmtime/memory.h
*
* Wasmtime API for interacting with wasm memories.
*/
#ifndef WASMTIME_MEMORY_H
#define WASMTIME_MEMORY_H
#include <wasm.h>
#include <wasmtime/extern.h>
#include <wasmtime/store.h>
#include <wasmtime/error.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* \brief Creates a new WebAssembly linear memory
*
* \param store the store to create the memory within
* \param ty the type of the memory to create
* \param ret where to store the returned memory
*
* If an error happens when creating the memory it's returned and owned by the
* caller. If an error happens then `ret` is not filled in.
*/
WASM_API_EXTERN wasmtime_error_t *wasmtime_memory_new(
wasmtime_context_t *store,
const wasm_memorytype_t* ty,
wasmtime_memory_t *ret
);
/**
* \brief Returns the tyep of the memory specified
*/
WASM_API_EXTERN wasm_memorytype_t* wasmtime_memory_type(
const wasmtime_context_t *store,
const wasmtime_memory_t *memory
);
/**
* \brief Returns the base pointer in memory where the linear memory starts.
*/
WASM_API_EXTERN uint8_t *wasmtime_memory_data(
const wasmtime_context_t *store,
const wasmtime_memory_t *memory
);
/**
* \brief Returns the byte length of this linear memory.
*/
WASM_API_EXTERN size_t wasmtime_memory_data_size(
const wasmtime_context_t *store,
const wasmtime_memory_t *memory
);
/**
* \brief Returns the length, in WebAssembly pages, of this linear memory
*/
WASM_API_EXTERN uint32_t wasmtime_memory_size(
const wasmtime_context_t *store,
const wasmtime_memory_t *memory
);
/**
* \brief Attempts to grow the specified memory by `delta` pages.
*
* \param store the store that owns `memory`
* \param memory the memory to grow
* \param delta the number of pages to grow by
* \param prev_size where to store the previous size of memory
*
* If memory cannot be grown then `prev_size` is left unchanged and an error is
* returned. Otherwise `prev_size` is set to the previous size of the memory, in
* WebAssembly pages, and `NULL` is returned.
*/
WASM_API_EXTERN wasmtime_error_t *wasmtime_memory_grow(
wasmtime_context_t *store,
const wasmtime_memory_t *memory,
uint32_t delta,
uint32_t *prev_size
);
#ifdef __cplusplus
} // extern "C"
#endif
#endif // WASMTIME_MEMORY_H

172
crates/c-api/include/wasmtime/module.h Normal file
View File

@@ -0,0 +1,172 @@
/**
* \file wasmtime/module.h
*
* APIs for interacting with modules in Wasmtime
*/
#ifndef WASMTIME_MODULE_H
#define WASMTIME_MODULE_H
#include <wasm.h>
#include <wasmtime/error.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* \brief An opaque object representing the type of a module.
*/
typedef struct wasmtime_moduletype wasmtime_moduletype_t;
/**
* \brief Deletes a module type.
*/
WASM_API_EXTERN void wasmtime_moduletype_delete(wasmtime_moduletype_t *ty);
/**
* \brief Returns the list of imports that this module type requires.
*
* This function does not take ownership of the provided module type but
* ownership of `out` is passed to the caller. Note that `out` is treated as
* uninitialized when passed to this function.
*/
WASM_API_EXTERN void wasmtime_moduletype_imports(const wasmtime_moduletype_t*, wasm_importtype_vec_t* out);
/**
* \brief Returns the list of exports that this module type provides.
*
* This function does not take ownership of the provided module type but
* ownership of `out` is passed to the caller. Note that `out` is treated as
* uninitialized when passed to this function.
*/
WASM_API_EXTERN void wasmtime_moduletype_exports(const wasmtime_moduletype_t*, wasm_exporttype_vec_t* out);
/**
* \brief Converts a #wasmtime_moduletype_t to a #wasm_externtype_t
*
* The returned value is owned by the #wasmtime_moduletype_t argument and should not
* be deleted.
*/
WASM_API_EXTERN wasm_externtype_t* wasmtime_moduletype_as_externtype(wasmtime_moduletype_t*);
/**
* \brief Attempts to convert a #wasm_externtype_t to a #wasmtime_moduletype_t
*
* The returned value is owned by the #wasmtime_moduletype_t argument and
* should not be deleted. Returns `NULL` if the provided argument is not a
* #wasmtime_moduletype_t.
*/
WASM_API_EXTERN wasmtime_moduletype_t* wasmtime_externtype_as_moduletype(wasm_externtype_t*);
/**
* \typedef wasmtime_module_t
* \brief Convenience alias for #wasmtime_module
*
* \struct wasmtime_module
* \brief A compiled Wasmtime module.
*
* This type represents a compiled WebAssembly module. The compiled module is
* ready to be instantiated and can be inspected for imports/exports. It is safe
* to use a module across multiple threads simultaneously.
*/
typedef struct wasmtime_module wasmtime_module_t;
/**
* \brief Compiles a WebAssembly binary into a #wasmtime_module_t
*
* This function will compile a WebAssembly binary into an owned #wasm_module_t.
* This performs the same as #wasm_module_new except that it returns a
* #wasmtime_error_t type to get richer error information.
*
* On success the returned #wasmtime_error_t is `NULL` and the `ret` pointer is
* filled in with a #wasm_module_t. On failure the #wasmtime_error_t is
* non-`NULL` and the `ret` pointer is unmodified.
*
* This function does not take ownership of any of its arguments, but the
* returned error and module are owned by the caller.
*/
WASM_API_EXTERN wasmtime_error_t *wasmtime_module_new(
wasm_engine_t *engine,
const uint8_t *wasm,
size_t wasm_len,
wasmtime_module_t **ret
);
/**
* \brief Deletes a module.
*/
WASM_API_EXTERN void wasmtime_module_delete(wasmtime_module_t *m);
/**
* \brief Creates a shallow clone of the specified module, increasing the
* internal reference count.
*/
WASM_API_EXTERN wasmtime_module_t *wasmtime_module_clone(wasmtime_module_t *m);
/**
* \brief Validate a WebAssembly binary.
*
* This function will validate the provided byte sequence to determine if it is
* a valid WebAssembly binary within the context of the engine provided.
*
* This function does not take ownership of its arguments but the caller is
* expected to deallocate the returned error if it is non-`NULL`.
*
* If the binary validates then `NULL` is returned, otherwise the error returned
* describes why the binary did not validate.
*/
WASM_API_EXTERN wasmtime_error_t *wasmtime_module_validate(
wasm_engine_t *engine,
const uint8_t *wasm,
size_t wasm_len
);
/**
* \brief Returns the type of this module.
*
* The returned #wasmtime_moduletype_t is expected to be deallocated by the
* caller.
*/
WASM_API_EXTERN wasmtime_moduletype_t* wasmtime_module_type(const wasmtime_module_t*);
/**
* \brief This function serializes compiled module artifacts as blob data.
*
* \param module the module
* \param ret if the conversion is successful, this byte vector is filled in with
* the serialized compiled module.
*
* \return a non-null error if parsing fails, or returns `NULL`. If parsing
* fails then `ret` isn't touched.
*
* This function does not take ownership of `module`, and the caller is
* expected to deallocate the returned #wasmtime_error_t and #wasm_byte_vec_t.
*/
WASM_API_EXTERN wasmtime_error_t* wasmtime_module_serialize(
wasmtime_module_t* module,
wasm_byte_vec_t *ret
);
/**
* \brief Build a module from serialized data.
*
* This function does not take ownership of any of its arguments, but the
* returned error and module are owned by the caller.
*
* This function is not safe to receive arbitrary user input. See the Rust
* documentation for more information on what inputs are safe to pass in here
* (e.g. only that of #wasmtime_module_serialize)
*/
WASM_API_EXTERN wasmtime_error_t *wasmtime_module_deserialize(
wasm_engine_t *engine,
const uint8_t *bytes,
size_t bytes_len,
wasmtime_module_t **ret
);
#ifdef __cplusplus
} // extern "C"
#endif
#endif // WASMTIME_MODULE_H

203
crates/c-api/include/wasmtime/store.h Normal file
View File

@@ -0,0 +1,203 @@
/**
* \file wasmtime/store.h
*
* Wasmtime definition of a "store".
*/
#ifndef WASMTIME_STORE_H
#define WASMTIME_STORE_H
#include <wasm.h>
#include <wasi.h>
#include <wasmtime/error.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* \typedef wasmtime_store_t
* \brief Convenience alias for #wasmtime_store_t
*
* \struct wasmtime_store
* \brief Storage of WebAssembly objects
*
* A store is the unit of isolation between WebAssembly instances in an
* embedding of Wasmtime. Values in one #wasmtime_store_t cannot flow into
* another #wasmtime_store_t. Stores are cheap to create and cheap to dispose.
* It's expected that one-off stores are common in embeddings.
*
* Objects stored within a #wasmtime_store_t are referenced with integer handles
* rather than interior pointers. This means that most APIs require that the
* store be explicitly passed in, which is done via #wasmtime_context_t. It is
* safe to move a #wasmtime_store_t to any thread at any time. A store generally
* cannot be concurrently used, however.
*/
typedef struct wasmtime_store wasmtime_store_t;
/**
* \typedef wasmtime_context_t
* \brief Convenience alias for #wasmtime_context
*
* \struct wasmtime_context
* \brief An interior pointer into a #wasmtime_store_t which is used as
* "context" for many functions.
*
* This context pointer is used pervasively throught Wasmtime's API. This can be
* acquired from #wasmtime_store_context or #wasmtime_caller_context. The
* context pointer for a store is the same for the entire lifetime of a store,
* so it can safely be stored adjacent to a #wasmtime_store_t itself.
*
* Usage of a #wasmtime_context_t must not outlive the original
* #wasmtime_store_t. Additionally #wasmtime_context_t can only be used in
* situations where it has explicitly been granted access to doing so. For
* example finalizers cannot use #wasmtime_context_t because they are not given
* access to it.
*/
typedef struct wasmtime_context wasmtime_context_t;
/**
* \brief Creates a new store within the specified engine.
*
* \param engine the compilation environment with configuration this store is
* connected to
* \param data user-provided data to store, can later be acquired with
* #wasmtime_context_get_data.
* \param finalizer an optional finalizer for `data`
*
* This function creates a fresh store with the provided configuration settings.
* The returned store must be deleted with #wasmtime_store_delete.
*/
WASM_API_EXTERN wasmtime_store_t *wasmtime_store_new(
wasm_engine_t *engine,
void *data,
void (*finalizer)(void*)
);
/**
* \brief Returns the interior #wasmtime_context_t pointer to this store
*/
WASM_API_EXTERN wasmtime_context_t *wasmtime_store_context(wasmtime_store_t *store);
/**
* \brief Deletes a store.
*/
WASM_API_EXTERN void wasmtime_store_delete(wasmtime_store_t *store);
/**
* \brief Returns the user-specified data associated with the specified store
*/
WASM_API_EXTERN void *wasmtime_context_get_data(const wasmtime_context_t* context);
/**
* \brief Overwrites the user-specified data associated with this store.
*
* Note that this does not execute the original finalizer for the provided data,
* and the original finalizer will be executed for the provided data when the
* store is deleted.
*/
WASM_API_EXTERN void wasmtime_context_set_data(wasmtime_context_t* context, void *data);
/**
* \brief Perform garbage collection within the given context.
*
* Garbage collects `externref`s that are used within this store. Any
* `externref`s that are discovered to be unreachable by other code or objects
* will have their finalizers run.
*
* The `context` argument must not be NULL.
*/
WASM_API_EXTERN void wasmtime_context_gc(wasmtime_context_t* context);
/**
* \brief Adds fuel to this context's store for wasm to consume while executing.
*
* For this method to work fuel consumption must be enabled via
* #wasmtime_config_consume_fuel_set. By default a store starts with 0 fuel
* for wasm to execute with (meaning it will immediately trap).
* This function must be called for the store to have
* some fuel to allow WebAssembly to execute.
*
* Note that at this time when fuel is entirely consumed it will cause
* wasm to trap. More usages of fuel are planned for the future.
*
* If fuel is not enabled within this store then an error is returned. If fuel
* is successfully added then NULL is returned.
*/
WASM_API_EXTERN wasmtime_error_t *wasmtime_context_add_fuel(wasmtime_context_t *store, uint64_t fuel);
/**
* \brief Returns the amount of fuel consumed by this context's store execution
* so far.
*
* If fuel consumption is not enabled via #wasmtime_config_consume_fuel_set
* then this function will return false. Otherwise true is returned and the
* fuel parameter is filled in with fuel consuemd so far.
*
* Also note that fuel, if enabled, must be originally configured via
* #wasmtime_context_add_fuel.
*/
WASM_API_EXTERN bool wasmtime_context_fuel_consumed(const wasmtime_context_t *context, uint64_t *fuel);
/**
* \brief Configres WASI state within the specified store.
*
* This function is required if #wasmtime_linker_define_wasi is called. This
* will configure the WASI state for instances defined within this store to the
* configuration specified.
*
* This function does not take ownership of `context` but it does take ownership
* of `wasi`. The caller should no longer use `wasi` after calling this function
* (even if an error is returned).
*/
WASM_API_EXTERN wasmtime_error_t *wasmtime_context_set_wasi(wasmtime_context_t *context, wasi_config_t *wasi);
/**
* \typedef wasmtime_interrupt_handle_t
* \brief Convenience alias for #wasmtime_interrupt_handle_t
*
* \struct wasmtime_interrupt_handle_t
* \brief A handle used to interrupt executing WebAssembly code.
*
* This structure is an opaque handle that represents a handle to a store. This
* handle can be used to remotely (from another thread) interrupt currently
* executing WebAssembly code.
*
* This structure is safe to share from multiple threads.
*/
typedef struct wasmtime_interrupt_handle wasmtime_interrupt_handle_t;
/**
* \brief Creates a new interrupt handle to interrupt executing WebAssembly from
* the provided store.
*
* There are a number of caveats about how interrupt is handled in Wasmtime. For
* more information see the [Rust
* documentation](https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Store.html#method.interrupt_handle).
*
* This function returns `NULL` if the store's configuration does not have
* interrupts enabled. See #wasmtime_config_interruptable_set.
*/
WASM_API_EXTERN wasmtime_interrupt_handle_t *wasmtime_interrupt_handle_new(wasmtime_context_t *context);
/**
* \brief Requests that WebAssembly code running in the store attached to this
* interrupt handle is interrupted.
*
* For more information about interrupts see #wasmtime_interrupt_handle_new.
*
* Note that this is safe to call from any thread.
*/
WASM_API_EXTERN void wasmtime_interrupt_handle_interrupt(wasmtime_interrupt_handle_t *handle);
/**
* \brief Deletes an interrupt handle.
*/
WASM_API_EXTERN void wasmtime_interrupt_handle_delete(wasmtime_interrupt_handle_t *handle);
#ifdef __cplusplus
} // extern "C"
#endif
#endif // WASMTIME_STORE_H

126
crates/c-api/include/wasmtime/table.h Normal file
View File

@@ -0,0 +1,126 @@
/**
* \file wasmtime/table.h
*
* Wasmtime APIs for interacting with WebAssembly tables.
*/
#ifndef WASMTIME_TABLE_H
#define WASMTIME_TABLE_H
#include <wasm.h>
#include <wasmtime/extern.h>
#include <wasmtime/store.h>
#include <wasmtime/error.h>
#include <wasmtime/val.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* \brief Creates a new host-defined wasm table.
*
* \param store the store to create the table within
* \param ty the type of the table to create
* \param init the initial value for this table's elements
* \param table where to store the returned table
*
* This function does not take ownership of any of its parameters, but yields
* ownership of returned error. This function may return an error if the `init`
* value does not match `ty`, for example.
*/
WASM_API_EXTERN wasmtime_error_t *wasmtime_table_new(
wasmtime_context_t *store,
const wasm_tabletype_t *ty,
const wasmtime_val_t *init,
wasmtime_table_t *table
);
/**
* \brief Returns the type of this table.
*
* The caller has ownership of the returned #wasm_tabletype_t
*/
WASM_API_EXTERN wasm_tabletype_t* wasmtime_table_type(
const wasmtime_context_t *store,
const wasmtime_table_t *table
);
/**
* \brief Gets a value in a table.
*
* \param store the store that owns `table`
* \param table the table to access
* \param index the table index to access
* \param val where to store the table's value
*
* This function will attempt to access a table element. If a nonzero value is
* returned then `val` is filled in and is owned by the caller. Otherwise zero
* is returned because the `index` is out-of-bounds.
*/
WASM_API_EXTERN bool wasmtime_table_get(
wasmtime_context_t *store,
const wasmtime_table_t *table,
uint32_t index,
wasmtime_val_t *val
);
/**
* \brief Sets a value in a table.
*
* \param store the store that owns `table`
* \param table the table to write to
* \param index the table index to write
* \param value the value to store.
*
* This function will store `value` into the specified index in the table. This
* does not take ownership of any argument but yields ownership of the error.
* This function can fail if `value` has the wrong type for the table, or if
* `index` is out of bounds.
*/
WASM_API_EXTERN wasmtime_error_t *wasmtime_table_set(
wasmtime_context_t *store,
const wasmtime_table_t *table,
uint32_t index,
const wasmtime_val_t *value
);
/**
* \brief Returns the size, in elements, of the specified table
*/
WASM_API_EXTERN uint32_t wasmtime_table_size(
const wasmtime_context_t *store,
const wasmtime_table_t *table
);
/**
* \brief Grows a table.
*
* \param store the store that owns `table`
* \param table the table to grow
* \param delta the number of elements to grow the table by
* \param init the initial value for new table element slots
* \param prev_size where to store the previous size of the table before growth
*
* This function will attempt to grow the table by `delta` table elements. This
* can fail if `delta` would exceed the maximum size of the table or if `init`
* is the wrong type for this table. If growth is successful then `NULL` is
* returned and `prev_size` is filled in with the previous size of the table, in
* elements, before the growth happened.
*
* This function does not take ownership of any of its arguments.
*/
WASM_API_EXTERN wasmtime_error_t *wasmtime_table_grow(
wasmtime_context_t *store,
const wasmtime_table_t *table,
uint32_t delta,
const wasmtime_val_t *init,
uint32_t *prev_size
);
#ifdef __cplusplus
} // extern "C"
#endif
#endif // WASMTIME_TABLE_H

60
crates/c-api/include/wasmtime/trap.h Normal file
View File

@@ -0,0 +1,60 @@
/**
* \file wasmtime/trap.h
*
* Wasmtime APIs for interacting with traps and extensions to #wasm_trap_t.
*/
#ifndef WASMTIME_TRAP_H
#define WASMTIME_TRAP_H
#include <wasm.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* \brief Creates a new trap.
*
* \param msg the message to associate with this trap
* \param msg_len the byte length of `msg`
*
* The #wasm_trap_t returned is owned by the caller.
*/
WASM_API_EXTERN wasm_trap_t *wasmtime_trap_new(const char *msg, size_t msg_len);
/**
* \brief Attempts to extract a WASI-specific exit status from this trap.
*
* Returns `true` if the trap is a WASI "exit" trap and has a return status. If
* `true` is returned then the exit status is returned through the `status`
* pointer. If `false` is returned then this is not a wasi exit trap.
*/
WASM_API_EXTERN bool wasmtime_trap_exit_status(const wasm_trap_t*, int *status);
/**
* \brief Returns a human-readable name for this frame's function.
*
* This function will attempt to load a human-readable name for function this
* frame points to. This function may return `NULL`.
*
* The lifetime of the returned name is the same as the #wasm_frame_t itself.
*/
WASM_API_EXTERN const wasm_name_t *wasmtime_frame_func_name(const wasm_frame_t*);
/**
* \brief Returns a human-readable name for this frame's module.
*
* This function will attempt to load a human-readable name for module this
* frame points to. This function may return `NULL`.
*
* The lifetime of the returned name is the same as the #wasm_frame_t itself.
*/
WASM_API_EXTERN const wasm_name_t *wasmtime_frame_module_name(const wasm_frame_t*);
#ifdef __cplusplus
} // extern "C"
#endif
#endif // WASMTIME_TRAP_H

158
crates/c-api/include/wasmtime/val.h Normal file
View File

@@ -0,0 +1,158 @@
/**
* \file wasmtime/val.h
*
* APIs for interacting with WebAssembly values in Wasmtime.
*/
#ifndef WASMTIME_VAL_H
#define WASMTIME_VAL_H
#include <wasm.h>
#include <wasmtime/extern.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* \typedef wasmtime_externref_t
* \brief Convenience alias for #wasmtime_externref
*
* \struct wasmtime_externref
* \brief A host-defined un-forgeable reference to pass into WebAssembly.
*
* This structure represents an `externref` that can be passed to WebAssembly.
* It cannot be forged by WebAssembly itself and is guaranteed to have been
* created by the host.
*/
typedef struct wasmtime_externref wasmtime_externref_t;
/**
* \brief Create a new `externref` value.
*
* Creates a new `externref` value wrapping the provided data, returning the
* pointer to the externref.
*
* \param data the host-specific data to wrap
* \param finalizer an optional finalizer for `data`
*
* When the reference is reclaimed, the wrapped data is cleaned up with the
* provided `finalizer`.
*
* The returned value must be deleted with #wasmtime_externref_delete
*/
WASM_API_EXTERN wasmtime_externref_t *wasmtime_externref_new(void *data, void (*finalizer)(void*));
/**
* \brief Get an `externref`'s wrapped data
*
* Returns the original `data` passed to #wasmtime_externref_new. It is required
* that `data` is not `NULL`.
*/
WASM_API_EXTERN void *wasmtime_externref_data(wasmtime_externref_t *data);
/**
* \brief Creates a shallow copy of the `externref` argument, returning a
* separately owned pointer (increases the reference count).
*/
WASM_API_EXTERN wasmtime_externref_t *wasmtime_externref_clone(wasmtime_externref_t *ref);
/**
* \brief Decrements the reference count of the `ref`, deleting it if it's the
* last reference.
*/
WASM_API_EXTERN void wasmtime_externref_delete(wasmtime_externref_t *ref);
/// \brief Discriminant stored in #wasmtime_val::kind
typedef uint8_t wasmtime_valkind_t;
/// \brief Value of #wasmtime_valkind_t meaning that #wasmtime_val_t is an i32
#define WASMTIME_I32 0
/// \brief Value of #wasmtime_valkind_t meaning that #wasmtime_val_t is an i64
#define WASMTIME_I64 1
/// \brief Value of #wasmtime_valkind_t meaning that #wasmtime_val_t is a f32
#define WASMTIME_F32 2
/// \brief Value of #wasmtime_valkind_t meaning that #wasmtime_val_t is a f64
#define WASMTIME_F64 3
/// \brief Value of #wasmtime_valkind_t meaning that #wasmtime_val_t is a v128
#define WASMTIME_V128 4
/// \brief Value of #wasmtime_valkind_t meaning that #wasmtime_val_t is a funcref
#define WASMTIME_FUNCREF 5
/// \brief Value of #wasmtime_valkind_t meaning that #wasmtime_val_t is an externref
#define WASMTIME_EXTERNREF 6
/// \brief A 128-bit value representing the WebAssembly `v128` type. Bytes are
/// stored in little-endian order.
typedef uint8_t wasmtime_v128[16];
/**
* \typedef wasmtime_valunion_t
* \brief Convenience alias for #wasmtime_valunion
*
* \union wasmtime_valunion
* \brief Container for different kinds of wasm values.
*
* This type is contained in #wasmtime_val_t and contains the payload for the
* various kinds of items a value can be.
*/
typedef union wasmtime_valunion {
/// Field used if #wasmtime_val_t::kind is #WASMTIME_I32
int32_t i32;
/// Field used if #wasmtime_val_t::kind is #WASMTIME_I64
int64_t i64;
/// Field used if #wasmtime_val_t::kind is #WASMTIME_F32
float32_t f32;
/// Field used if #wasmtime_val_t::kind is #WASMTIME_F64
float64_t f64;
/// Field used if #wasmtime_val_t::kind is #WASMTIME_FUNCREF
///
/// If this value represents a `ref.null func` value then the `store_id` field
/// is set to zero.
wasmtime_func_t funcref;
/// Field used if #wasmtime_val_t::kind is #WASMTIME_EXTERNREF
///
/// If this value represents a `ref.null extern` value then this pointer will
/// be `NULL`.
wasmtime_externref_t *externref;
/// Field used if #wasmtime_val_t::kind is #WASMTIME_V128
wasmtime_v128 v128;
} wasmtime_valunion_t;
/**
* \typedef wasmtime_val_t
* \brief Convenience alias for #wasmtime_val_t
*
* \union wasmtime_val
* \brief Container for different kinds of wasm values.
*
* Note that this structure may contain an owned value, namely
* #wasmtime_externref_t, depending on the context in which this is used. APIs
* which consume a #wasmtime_val_t do not take ownership, but APIs that return
* #wasmtime_val_t require that #wasmtime_val_delete is called to deallocate
* the value.
*/
typedef struct wasmtime_val {
/// Discriminant of which field of #of is valid.
wasmtime_valkind_t kind;
/// Container for the extern item's value.
wasmtime_valunion_t of;
} wasmtime_val_t;
/**
* \brief Delets an owned #wasmtime_val_t.
*
* Note that this only deletes the contents, not the memory that `val` points to
* itself (which is owned by the caller).
*/
WASM_API_EXTERN void wasmtime_val_delete(wasmtime_val_t *val);
/**
* \brief Copies `src` into `dst`.
*/
WASM_API_EXTERN void wasmtime_val_copy(wasmtime_val_t *dst, const wasmtime_val_t *src);
#ifdef __cplusplus
} // extern "C"
#endif
#endif // WASMTIME_VAL_H