Skip to main content

Runtime APIs

The Extism runtime is implemented as a Rust crate, from which we generate C headers so that any language with a C-compatible FFI can bind functions to the runtime itself and embed Extism. This is how the official SDKs are created.

If you would like to embed Extism into a language that we currently do not support, you should take a look at the header file linked above.

The general set of functions that is necessary to satisfy the runtime requirements is:


Create a new context.

struct ExtismContext *extism_context_new(void);


Free a context.

void extism_context_free(struct ExtismContext *ctx);


Create a new plugin.

  • wasm: is a WASM module (wat or wasm) or a JSON encoded manifest
  • wasm_size: the length of the wasm parameter
  • functions: is an array of ExtismFunction*
  • n_functions: is the number of functions
  • with_wasi: enables/disables WASI
ExtismPlugin extism_plugin_new(struct ExtismContext *ctx,
const uint8_t *wasm,
ExtismSize wasm_size,
const ExtismFunction **functions,
ExtismSize n_functions,
bool with_wasi);


Update a plugin, keeping the existing ID.

Similar to extism_plugin_new but takes an index argument to specify which plugin to update.

Memory for this plugin will be reset upon update.

bool extism_plugin_update(struct ExtismContext *ctx,
ExtismPlugin index,
const uint8_t *wasm,
ExtismSize wasm_size,
const ExtismFunction **functions,
ExtismSize n_functions,
bool with_wasi);


Remove a plugin from the registry and free associated memory.

void extism_plugin_free(struct ExtismContext *ctx, ExtismPlugin plugin);


Remove all plugins from the registry.

void extism_context_reset(struct ExtismContext *ctx);


Update plugin config values, this will merge with the existing values.

bool extism_plugin_config(struct ExtismContext *ctx,
ExtismPlugin plugin,
const uint8_t *json,
ExtismSize json_size);


Returns true if func_name exists.

bool extism_plugin_function_exists(struct ExtismContext *ctx,
ExtismPlugin plugin,
const char *func_name);


Call a function.

  • func_name: is the function to call
  • data: is the input data
  • data_len: is the length of data
int32_t extism_plugin_call(struct ExtismContext *ctx,
ExtismPlugin plugin_id,
const char *func_name,
const uint8_t *data,
ExtismSize data_len);


Get the error associated with a Context or Plugin, if plugin is -1 then the context error will be returned.

const char *extism_error(struct ExtismContext *ctx, ExtismPlugin plugin);


Get the length of a plugin's output data.

ExtismSize extism_plugin_output_length(struct ExtismContext *ctx, ExtismPlugin plugin);


Get the plugin's output data.

const uint8_t *extism_plugin_output_data(struct ExtismContext *ctx, ExtismPlugin plugin);


Set log file and level.

bool extism_log_file(const char *filename, const char *log_level);


Get the Extism version string.

const char *extism_version(void);


Returns a pointer to the memory of the currently running plugin

uint8_t *extism_current_plugin_memory(ExtismCurrentPlugin *plugin);


Allocate a memory block in the currently running plugin

uint64_t extism_current_plugin_memory_alloc(ExtismCurrentPlugin *plugin, ExtismSize n);


Get the length of an allocated block

ExtismSize extism_current_plugin_memory_length(ExtismCurrentPlugin *plugin, ExtismSize n);


Free an allocated memory block

void extism_current_plugin_memory_free(ExtismCurrentPlugin *plugin, uint64_t ptr);


Create a new host function

  • name: function name, this should be valid UTF-8
  • inputs: argument types
  • n_inputs: number of argument types
  • outputs: return types
  • n_outputs: number of return types
  • func: the function to call
  • user_data: a pointer that will be passed to the function when it's called this value should live as long as the function exists
  • free_user_data: a callback to release the user_data value when the resulting ExtismFunction is freed.

Returns a new ExtismFunction or null if the name argument is invalid.

ExtismFunction *extism_function_new(const char *name,
const ExtismValType *inputs,
ExtismSize n_inputs,
const ExtismValType *outputs,
ExtismSize n_outputs,
ExtismFunctionType func,
void *user_data,
void (*free_user_data)(void *_));


Set the namespace of an ExtismFunction

void extism_function_set_namespace(ExtismFunction *ptr, const char *namespace_);


Free an ExtismFunction

void extism_function_free(ExtismFunction *ptr);

Type definitions:


A Context is used to store and manage plugins

typedef struct ExtismContext ExtismContext;


typedef int32_t ExtismPlugin;


typedef uint64_t ExtismSize;


ExtismFunction is used to register host functions with plugins

typedef struct ExtismFunction ExtismFunction;


ExtismCurrentPlugin provides access to the currently executing plugin from within a host function

typedef struct ExtismCurrentPlugin ExtismCurrentPlugin;