369 lines
14 KiB
C
369 lines
14 KiB
C
/**
|
|
* \file wasmtime/async.h
|
|
*
|
|
* \brief Wasmtime async functionality
|
|
*
|
|
* Async functionality in Wasmtime is well documented here:
|
|
* https://docs.wasmtime.dev/api/wasmtime/struct.Config.html#method.async_support
|
|
*
|
|
* All WebAssembly executes synchronously, but an async support enables the Wasm code
|
|
* be executed on a seperate stack, so it can be paused and resumed. There are three
|
|
* mechanisms for yielding control from wasm to the caller: fuel, epochs, and async host functions.
|
|
*
|
|
* When WebAssembly is executed, a #wasmtime_call_future_t is returned. This struct represents the
|
|
* state of the execution and each call to #wasmtime_call_future_poll will execute the WebAssembly
|
|
* code on a seperate stack until the function returns or yields control back to the caller.
|
|
*
|
|
* It's expected these futures are pulled in a loop until completed, at which point the future
|
|
* should be deleted. Functions that return a #wasmtime_call_future_t are special in that all
|
|
* parameters to that function should not be modified in any way and must be kept alive until
|
|
* the future is deleted. This includes concurrent calls for a single store - another function
|
|
* on a store should not be called while there is a #wasmtime_call_future_t alive.
|
|
*
|
|
* As for asynchronous host calls - the reverse contract is upheld. Wasmtime will keep all parameters
|
|
* to the function alive and unmodified until the #wasmtime_func_async_continuation_callback_t returns
|
|
* true.
|
|
*
|
|
*/
|
|
|
|
#ifndef WASMTIME_ASYNC_H
|
|
#define WASMTIME_ASYNC_H
|
|
|
|
#include <wasm.h>
|
|
#include <wasmtime/error.h>
|
|
#include <wasmtime/config.h>
|
|
#include <wasmtime/store.h>
|
|
#include <wasmtime/func.h>
|
|
#include <wasmtime/linker.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* \brief Whether or not to enable support for asynchronous functions in Wasmtime.
|
|
*
|
|
* When enabled, the config can optionally define host functions with async.
|
|
* Instances created and functions called with this Config must be called through their asynchronous APIs, however.
|
|
* For example using wasmtime_func_call will panic when used with this config.
|
|
*
|
|
* For more information see the Rust documentation at
|
|
* https://docs.wasmtime.dev/api/wasmtime/struct.Config.html#method.async_support
|
|
*/
|
|
WASMTIME_CONFIG_PROP(void, async_support, bool)
|
|
|
|
/**
|
|
* \brief Configures the size of the stacks used for asynchronous execution.
|
|
*
|
|
* This setting configures the size of the stacks that are allocated for asynchronous execution.
|
|
*
|
|
* The value cannot be less than max_wasm_stack.
|
|
*
|
|
* The amount of stack space guaranteed for host functions is async_stack_size - max_wasm_stack, so take care
|
|
* not to set these two values close to one another; doing so may cause host functions to overflow the stack
|
|
* and abort the process.
|
|
*
|
|
* By default this option is 2 MiB.
|
|
*
|
|
* For more information see the Rust documentation at
|
|
* https://docs.wasmtime.dev/api/wasmtime/struct.Config.html#method.async_stack_size
|
|
*/
|
|
WASMTIME_CONFIG_PROP(void, async_stack_size, uint64_t)
|
|
|
|
/**
|
|
* \brief Configures a Store to yield execution of async WebAssembly code
|
|
* periodically.
|
|
*
|
|
* When a Store is configured to consume fuel with
|
|
* `wasmtime_config_consume_fuel` this method will configure what happens when
|
|
* fuel runs out. Specifically executing WebAssembly will be suspended and
|
|
* control will be yielded back to the caller.
|
|
*
|
|
* This is only suitable with use of a store associated with an async config
|
|
* because only then are futures used and yields are possible.
|
|
*
|
|
* \param context the context for the store to configure.
|
|
* \param interval the amount of fuel at which to yield. A value of 0 will
|
|
* disable yielding.
|
|
*/
|
|
WASM_API_EXTERN void
|
|
wasmtime_context_fuel_async_yield_interval(wasmtime_context_t *context,
|
|
uint64_t interval);
|
|
|
|
/**
|
|
* \brief Configures epoch-deadline expiration to yield to the async caller and the update the deadline.
|
|
*
|
|
* This is only suitable with use of a store associated with an async config because
|
|
* only then are futures used and yields are possible.
|
|
*
|
|
* See the Rust documentation for more:
|
|
* https://docs.wasmtime.dev/api/wasmtime/struct.Store.html#method.epoch_deadline_async_yield_and_update
|
|
*/
|
|
WASM_API_EXTERN wasmtime_error_t* wasmtime_context_epoch_deadline_async_yield_and_update(
|
|
wasmtime_context_t *context,
|
|
uint64_t delta);
|
|
|
|
/**
|
|
* The callback to determine a continuation's current state.
|
|
*
|
|
* Return true if the host call has completed, otherwise false will
|
|
* continue to yield WebAssembly execution.
|
|
*/
|
|
typedef bool (*wasmtime_func_async_continuation_callback_t)(void *env);
|
|
|
|
/**
|
|
* A continuation for the current state of the host function's execution.
|
|
*/
|
|
typedef struct wasmtime_async_continuation_t {
|
|
/// Callback for if the async function has completed.
|
|
wasmtime_func_async_continuation_callback_t callback;
|
|
/// User-provided argument to pass to the callback.
|
|
void *env;
|
|
/// A finalizer for the user-provided *env
|
|
void (*finalizer)(void *);
|
|
} wasmtime_async_continuation_t;
|
|
|
|
/**
|
|
* \brief Callback signature for #wasmtime_linker_define_async_func.
|
|
*
|
|
* This is a host function that returns a continuation to be called later.
|
|
*
|
|
* All the arguments to this function will be kept alive until the continuation
|
|
* returns that it has errored or has completed.
|
|
*
|
|
* \param env user-provided argument passed to #wasmtime_linker_define_async_func
|
|
* \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
|
|
* \param trap_ret if assigned a not `NULL` value then the called function will
|
|
* trap with the returned error. Note that ownership of trap is transferred
|
|
* to wasmtime.
|
|
* \param continuation_ret the returned continuation that determines when the
|
|
* async function has completed executing.
|
|
*
|
|
* Only supported for async stores.
|
|
*
|
|
* See #wasmtime_func_callback_t for more information.
|
|
*/
|
|
typedef void (*wasmtime_func_async_callback_t)(
|
|
void *env,
|
|
wasmtime_caller_t *caller,
|
|
const wasmtime_val_t *args,
|
|
size_t nargs,
|
|
wasmtime_val_t *results,
|
|
size_t nresults,
|
|
wasm_trap_t** trap_ret,
|
|
wasmtime_async_continuation_t * continuation_ret);
|
|
|
|
/**
|
|
* \brief The structure representing a asynchronously running function.
|
|
*
|
|
* This structure is always owned by the caller and must be deleted using #wasmtime_call_future_delete.
|
|
*
|
|
* Functions that return this type require that the parameters to the function are unmodified until
|
|
* this future is destroyed.
|
|
*/
|
|
typedef struct wasmtime_call_future wasmtime_call_future_t;
|
|
|
|
/**
|
|
* \brief Executes WebAssembly in the function.
|
|
*
|
|
* Returns true if the function call has completed. After this function returns true, it should *not* be
|
|
* called again for a given future.
|
|
*
|
|
* This function returns false if execution has yielded either due to being out of fuel
|
|
* (see wasmtime_context_fuel_async_yield_interval), or the epoch has been incremented enough
|
|
* (see wasmtime_context_epoch_deadline_async_yield_and_update). The function may also return false if
|
|
* asynchronous host functions have been called, which then calling this function will call the
|
|
* continuation from the async host function.
|
|
*
|
|
* For more see the information at
|
|
* https://docs.wasmtime.dev/api/wasmtime/struct.Config.html#asynchronous-wasm
|
|
*
|
|
*/
|
|
WASM_API_EXTERN bool wasmtime_call_future_poll(wasmtime_call_future_t *future);
|
|
|
|
/**
|
|
* /brief Frees the underlying memory for a future.
|
|
*
|
|
* All wasmtime_call_future_t are owned by the caller and should be deleted using this function.
|
|
*/
|
|
WASM_API_EXTERN void wasmtime_call_future_delete(wasmtime_call_future_t *future);
|
|
|
|
/**
|
|
* \brief Invokes this function with the params given, returning the results asynchronously.
|
|
*
|
|
* This function is the same as wasmtime_func_call except that it is asynchronous.
|
|
* This is only compatible with stores associated with an asynchronous config.
|
|
*
|
|
* The result is a future that is owned by the caller and must be deleted via #wasmtime_call_future_delete.
|
|
*
|
|
* The `args` and `results` pointers may be `NULL` if the corresponding length is zero.
|
|
* The `trap_ret` and `error_ret` pointers may *not* be `NULL`.
|
|
*
|
|
* Does not take ownership of #wasmtime_val_t arguments or #wasmtime_val_t results,
|
|
* and all parameters to this function must be kept alive and not modified until the
|
|
* returned #wasmtime_call_future_t is deleted. This includes the context and store
|
|
* parameters. Only a single future can be alive for a given store at a single time
|
|
* (meaning only call this function after the previous call's future was deleted).
|
|
*
|
|
* See the header documentation for for more information.
|
|
*
|
|
* For more information see the Rust documentation at
|
|
* https://docs.wasmtime.dev/api/wasmtime/struct.Func.html#method.call_async
|
|
*/
|
|
WASM_API_EXTERN wasmtime_call_future_t* wasmtime_func_call_async(
|
|
wasmtime_context_t *context,
|
|
const wasmtime_func_t *func,
|
|
const wasmtime_val_t *args,
|
|
size_t nargs,
|
|
wasmtime_val_t *results,
|
|
size_t nresults,
|
|
wasm_trap_t** trap_ret,
|
|
wasmtime_error_t** error_ret);
|
|
|
|
/**
|
|
* \brief Defines a new async function in this linker.
|
|
*
|
|
* This function behaves similar to #wasmtime_linker_define_func, except it supports async
|
|
* callbacks.
|
|
*
|
|
* The callback `cb` will be invoked on another stack (fiber for Windows).
|
|
*/
|
|
WASM_API_EXTERN wasmtime_error_t *wasmtime_linker_define_async_func(
|
|
wasmtime_linker_t *linker,
|
|
const char *module,
|
|
size_t module_len,
|
|
const char *name,
|
|
size_t name_len,
|
|
const wasm_functype_t *ty,
|
|
wasmtime_func_async_callback_t cb,
|
|
void *data,
|
|
void (*finalizer)(void *));
|
|
|
|
/**
|
|
* \brief Instantiates a #wasm_module_t with the items defined in this linker for an async store.
|
|
*
|
|
* This is the same as #wasmtime_linker_instantiate but used for async stores
|
|
* (which requires functions are called asynchronously). The returning #wasmtime_call_future_t
|
|
* must be polled using #wasmtime_call_future_poll, and is owned and must be deleted using #wasmtime_call_future_delete.
|
|
*
|
|
* The `trap_ret` and `error_ret` pointers may *not* be `NULL` and the returned memory is owned by the caller.
|
|
*
|
|
* All arguments to this function must outlive the returned future and be unmodified until the future is deleted.
|
|
*/
|
|
WASM_API_EXTERN wasmtime_call_future_t *wasmtime_linker_instantiate_async(
|
|
const wasmtime_linker_t *linker,
|
|
wasmtime_context_t *store,
|
|
const wasmtime_module_t *module,
|
|
wasmtime_instance_t *instance,
|
|
wasm_trap_t** trap_ret,
|
|
wasmtime_error_t** error_ret);
|
|
|
|
/**
|
|
* \brief Instantiates instance within the given store.
|
|
*
|
|
* This will also run the function's startup function, if there is one.
|
|
*
|
|
* For more information on async instantiation see #wasmtime_linker_instantiate_async.
|
|
*
|
|
* \param instance_pre the pre-initialized instance
|
|
* \param store the store in which to create the instance
|
|
* \param instance where to store the returned instance
|
|
* \param trap_ret where to store the returned trap
|
|
* \param error_ret where to store the returned trap
|
|
*
|
|
* The `trap_ret` and `error_ret` pointers may *not* be `NULL` and the returned memory is owned by the caller.
|
|
*
|
|
* All arguments to this function must outlive the returned future and be unmodified until the future is deleted.
|
|
*/
|
|
WASM_API_EXTERN wasmtime_call_future_t *wasmtime_instance_pre_instantiate_async(
|
|
const wasmtime_instance_pre_t* instance_pre,
|
|
wasmtime_context_t *store,
|
|
wasmtime_instance_t *instance,
|
|
wasm_trap_t** trap_ret,
|
|
wasmtime_error_t** error_ret);
|
|
|
|
/**
|
|
* A callback to get the top of the stack address and the length of the stack,
|
|
* excluding guard pages.
|
|
*
|
|
* For more information about the parameters see the Rust documentation at
|
|
* https://docs.wasmtime.dev/api/wasmtime/trait.StackMemory.html
|
|
*/
|
|
typedef uint8_t *(*wasmtime_stack_memory_get_callback_t)(
|
|
void *env,
|
|
size_t *out_len);
|
|
|
|
/**
|
|
* A Stack instance created from a #wasmtime_new_stack_memory_callback_t.
|
|
*
|
|
* For more information see the Rust documentation at
|
|
* https://docs.wasmtime.dev/api/wasmtime/trait.StackMemory.html
|
|
*/
|
|
typedef struct {
|
|
/// User provided value to be passed to get_memory and grow_memory
|
|
void *env;
|
|
/// Callback to get the memory and size of this LinearMemory
|
|
wasmtime_stack_memory_get_callback_t get_stack_memory;
|
|
/// An optional finalizer for env
|
|
void (*finalizer)(void*);
|
|
} wasmtime_stack_memory_t;
|
|
|
|
/**
|
|
* A callback to create a new StackMemory from the specified parameters.
|
|
*
|
|
* The result should be written to `stack_ret` and wasmtime will own the values written
|
|
* into that struct.
|
|
*
|
|
* This callback must be thread-safe.
|
|
*
|
|
* For more information about the parameters see the Rust documentation at
|
|
* https://docs.wasmtime.dev/api/wasmtime/trait.StackCreator.html#tymethod.new_stack
|
|
*/
|
|
typedef wasmtime_error_t *(*wasmtime_new_stack_memory_callback_t)(
|
|
void *env,
|
|
size_t size,
|
|
wasmtime_stack_memory_t *stack_ret);
|
|
|
|
/**
|
|
* A representation of custom stack creator.
|
|
*
|
|
* For more information see the Rust documentation at
|
|
* https://docs.wasmtime.dev/api/wasmtime/trait.StackCreator.html
|
|
*/
|
|
typedef struct {
|
|
/// User provided value to be passed to new_stack
|
|
void* env;
|
|
/// The callback to create a new stack, must be thread safe
|
|
wasmtime_new_stack_memory_callback_t new_stack;
|
|
/// An optional finalizer for env.
|
|
void (*finalizer)(void*);
|
|
} wasmtime_stack_creator_t;
|
|
|
|
/**
|
|
* Sets a custom stack creator.
|
|
*
|
|
* Custom memory creators are used when creating creating async instance stacks for
|
|
* the on-demand instance allocation strategy.
|
|
*
|
|
* The config does **not** take ownership of the #wasmtime_stack_creator_t passed in, but
|
|
* instead copies all the values in the struct.
|
|
*
|
|
* For more information see the Rust documentation at
|
|
* https://docs.wasmtime.dev/api/wasmtime/struct.Config.html#method.with_host_stack
|
|
*/
|
|
WASM_API_EXTERN void wasmtime_config_host_stack_creator_set(
|
|
wasm_config_t*,
|
|
wasmtime_stack_creator_t*);
|
|
|
|
|
|
#ifdef __cplusplus
|
|
} // extern "C"
|
|
#endif
|
|
|
|
#endif // WASMTIME_ASYNC_H
|
|
|