Wasmtime
store.h File Reference
#include <wasm.h>
#include <wasi.h>
#include <wasmtime/error.h>

Go to the source code of this file.

Typedefs

typedef struct wasmtime_store wasmtime_store_t
 Convenience alias for wasmtime_store_t.
 
typedef struct wasmtime_context wasmtime_context_t
 Convenience alias for wasmtime_context.
 

Functions

wasmtime_store_twasmtime_store_new (wasm_engine_t *engine, void *data, void(*finalizer)(void *))
 Creates a new store within the specified engine. More...
 
wasmtime_context_twasmtime_store_context (wasmtime_store_t *store)
 Returns the interior wasmtime_context_t pointer to this store.
 
void wasmtime_store_delete (wasmtime_store_t *store)
 Deletes a store.
 
void * wasmtime_context_get_data (const wasmtime_context_t *context)
 Returns the user-specified data associated with the specified store.
 
void wasmtime_context_set_data (wasmtime_context_t *context, void *data)
 Overwrites the user-specified data associated with this store. More...
 
void wasmtime_context_gc (wasmtime_context_t *context)
 Perform garbage collection within the given context. More...
 
wasmtime_error_twasmtime_context_add_fuel (wasmtime_context_t *store, uint64_t fuel)
 Adds fuel to this context's store for wasm to consume while executing. More...
 
bool wasmtime_context_fuel_consumed (const wasmtime_context_t *context, uint64_t *fuel)
 Returns the amount of fuel consumed by this context's store execution so far. More...
 
wasmtime_error_twasmtime_context_consume_fuel (wasmtime_context_t *context, uint64_t fuel, uint64_t *remaining)
 Attempt to manually consume fuel from the store. More...
 
wasmtime_error_twasmtime_context_set_wasi (wasmtime_context_t *context, wasi_config_t *wasi)
 Configures WASI state within the specified store. More...
 
void wasmtime_context_set_epoch_deadline (wasmtime_context_t *context, uint64_t ticks_beyond_current)
 Configures the relative deadline at which point WebAssembly code will trap. More...
 

Detailed Description

Wasmtime definition of a "store".

Function Documentation

◆ wasmtime_context_add_fuel()

wasmtime_error_t * wasmtime_context_add_fuel ( wasmtime_context_t store,
uint64_t  fuel 
)

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.

◆ wasmtime_context_consume_fuel()

wasmtime_error_t * wasmtime_context_consume_fuel ( wasmtime_context_t context,
uint64_t  fuel,
uint64_t *  remaining 
)

Attempt to manually consume fuel from the store.

If fuel consumption is not enabled via wasmtime_config_consume_fuel_set then this function will return an error. Otherwise this will attempt to consume the specified amount of fuel from the store. If successful the remaining amount of fuel is stored into remaining. If fuel couldn't be consumed then an error is returned.

Also note that fuel, if enabled, must be originally configured via wasmtime_context_add_fuel.

◆ wasmtime_context_fuel_consumed()

bool wasmtime_context_fuel_consumed ( const wasmtime_context_t context,
uint64_t *  fuel 
)

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.

◆ wasmtime_context_gc()

void wasmtime_context_gc ( wasmtime_context_t context)

Perform garbage collection within the given context.

Garbage collects externrefs that are used within this store. Any externrefs that are discovered to be unreachable by other code or objects will have their finalizers run.

The context argument must not be NULL.

◆ wasmtime_context_set_data()

void wasmtime_context_set_data ( wasmtime_context_t context,
void *  data 
)

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.

◆ wasmtime_context_set_epoch_deadline()

void wasmtime_context_set_epoch_deadline ( wasmtime_context_t context,
uint64_t  ticks_beyond_current 
)

Configures the relative deadline at which point WebAssembly code will trap.

This function configures the store-local epoch deadline after which point WebAssembly code will trap.

See also wasmtime_config_epoch_interruption_set.

◆ wasmtime_context_set_wasi()

wasmtime_error_t * wasmtime_context_set_wasi ( wasmtime_context_t context,
wasi_config_t wasi 
)

Configures 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).

◆ wasmtime_store_new()

wasmtime_store_t * wasmtime_store_new ( wasm_engine_t engine,
void *  data,
void(*)(void *)  finalizer 
)

Creates a new store within the specified engine.

Parameters
enginethe compilation environment with configuration this store is connected to
datauser-provided data to store, can later be acquired with wasmtime_context_get_data.
finalizeran 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.