Skip to main content

Runtime APIs

The Extism runtime is implemented as a Rust crate and has a C API. The C API enables embedding the runtime in any language with C-compatible FFI. Many of the official SDKs are built on top of the C API.

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:

extism_plugin_new​

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
  • errmsg: error message during plugin creation, this should be freed with extism_plugin_new_error_free
ExtismPlugin extism_plugin_new(const uint8_t *wasm,
                               ExtismSize wasm_size,
                               const ExtismFunction **functions,
                               ExtismSize n_functions,
                               bool with_wasi,
                               char **errmsg);

extism_plugin_new_error_free​

Frees the error message returned when creating a plugin

void extism_plugin_new_error_free(char *err);

extism_plugin_free​

Remove a plugin from the registry and free associated memory.

void extism_plugin_free(ExtismPlugin *plugin);

extism_plugin_config​

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

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

extism_plugin_function_exists​

Returns true if func_name exists.

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

extism_plugin_call​

Call a function.

  • func_name: is the function to call
  • data: is the input data
  • data_len: is the length of data

Returns 0 when the call is successful.

int32_t extism_plugin_call(ExtismPlugin *plugin,
                           const char *func_name,
                           const uint8_t *data,
                           ExtismSize data_len);

extism_plugin_call_with_host_context​

Call a function with additional host context that can be accessed from inside host functions.

  • func_name: is the function to call
  • data: is the input data
  • data_len: is the length of data
  • host_ctx: an opaque pointer that can be accessed in host functions

Returns 0 when the call is successful.

int32_t extism_plugin_call_with_host_context(ExtismPlugin *plugin,
                           const char *func_name,
                           const uint8_t *data,
                           ExtismSize data_len,
                           void *host_ctx);

extism_plugin_error​

Get the error associated with a Plugin

const char *extism_plugin_error(ExtismPlugin *plugin);

extism_plugin_output_length​

Get the length of a plugin's output data.

ExtismSize extism_plugin_output_length(ExtismPlugin *plugin);

extism_plugin_output_data​

Get the plugin's output data.

const uint8_t *extism_plugin_output_data(ExtismPlugin *plugin);

extism_plugin_reset​

Reset the Extism runtime, this will invalidate all allocated memory.

bool extism_plugin_reset(ExtismPlugin *plugin);

extism_log_file​

Set log file and level.

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

extism_log_custom​

Enable a custom log handler, this will buffer logs until extism_log_drain is called Log level should be one of: info, error, trace, debug, warn

bool extism_log_custom(const char *log_level);

extism_log_drain​

Calls the provided callback function for each buffered log line. This is only needed when extism_log_custom is used.

void extism_log_drain(void (*handler)(const char *, uintptr_t));

extism_version​

Get the Extism version string.

const char *extism_version(void);

extism_current_plugin_memory​

Returns a pointer to the memory of the currently running plugin

uint8_t *extism_current_plugin_memory(ExtismCurrentPlugin *plugin);

extism_current_plugin_host_context​

Get access to the host context, passed in using extism_plugin_call_with_host_context

void *extism_current_plugin_host_context(ExtismCurrentPlugin *plugin);

extism_current_plugin_memory_alloc​

Allocate a memory block in the currently running plugin

uint64_t extism_current_plugin_memory_alloc(ExtismCurrentPlugin *plugin, ExtismSize n);

extism_current_plugin_memory_length​

Get the length of an allocated block

ExtismSize extism_current_plugin_memory_length(ExtismCurrentPlugin *plugin, ExtismSize n);

extism_current_plugin_memory_free​

Free an allocated memory block

void extism_current_plugin_memory_free(ExtismCurrentPlugin *plugin, uint64_t ptr);

extism_function_new​

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 *_));

extism_function_set_namespace​

Set the namespace of an ExtismFunction

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

extism_function_free​

Free an ExtismFunction

void extism_function_free(ExtismFunction *ptr);

extism_plugin_cancel_handle​

Get handle for plugin cancellation

const ExtismCancelHandle *extism_plugin_cancel_handle(const ExtismPlugin *plugin);

extism_plugin_cancel​

Cancel a running plugin from another thread

bool extism_plugin_cancel(const ExtismCancelHandle *handle);

Type definitions:​

ExtismPlugin​

typedef struct ExtismPlugin ExtismPlugin;

ExtismSize​

typedef uint64_t ExtismSize;

ExtismFunction​

ExtismFunction is used to register host functions with plugins

typedef struct ExtismFunction ExtismFunction;

ExtismCurrentPlugin​

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

typedef struct ExtismCurrentPlugin ExtismCurrentPlugin;

ExtismCancelHandle​

ExtismCancelHandle can be used to cancel a running plugin from another thread

typedef struct ExtismCancelHandle ExtismCancelHandle;