Extism (p.extism.1.2.0.doc.extism.Extism)

Introduction

Extism is a framework for executing WebAssembly plugins. The OCaml bindings require libextism, installation information is available on the Extism website

The Plugin and Manifest modules are the main modules to look at.
Type provides different types that can be encoded as input/output to Plugin.call
Function is used to define host functions and Host_function is used from inside host functions to access the plugin memory

Basic example

The following loads a Plugin from a file on disk using Manifest then calls a function with a string and prints the string output:

  open Extism

  let () =
    let plugin =
      Plugin.of_manifest_exn
      @@ Manifest.create [ Manifest.Wasm.file "test/code.wasm" ]
    in
    let res =
      Plugin.call_string_exn plugin ~name:"count_vowels" "input data"
    in
    print_endline res

Using the typed plugin interface you can pre-define plug-in functions:

  open Extism

  module Example = struct
    include Plugin.Typed.Init ()

    let count_vowels = exn @@ fn "count_vowels" Type.string Type.string
  end

  let () =
    let plugin =
      Example.of_plugin_exn
      @@ Plugin.of_manifest_exn
      @@ Manifest.create [ Manifest.Wasm.file "test/code.wasm" ]
    in
    let res =
      Example.count_vowels plugin "input data"
    in
    print_endline res

API

Sourcemodule Manifest = Extism_manifest

The Manifest module is a reference to the Extism_manifest package, it allows you to programatically construct Extism manifests.

Sourcemodule Val_type : sig ... end

Val_type enumerates the available Wasm types, this should only be used when implementing host functions

Sourcemodule Val : sig ... end

Val represents low-level WebAssembly values

Sourcemodule Type : sig ... end

Type defines conversions from OCaml values in and out of Extism memory

Sourcemodule Host_function : sig ... end

Host_function represents the plugin that is currently running from inside a host function definition

Sourcemodule Function : sig ... end

Function is used to create new a new function, which can be called from a WebAssembly plugin

Sourcemodule Plugin : sig ... end

Plugins contain functions that can be called

Source

val set_log_file : 
  ?level:[ `Error | `Warn | `Info | `Debug | `Trace | `Filter of string ] ->
  string ->
  bool

Set the log file and level for all Extism plugins, the names stdout or stderr can be used to write to the terminal

Sourcetype drain_logs = unit -> unit

Source

val set_log_custom : 
  ?level:[ `Error | `Warn | `Info | `Debug | `Trace | `Filter of string ] ->
  (string -> unit) ->
  drain_logs

Set the log level and enable buffered logging. Returns a function that can be used to drain the logs

Sourcemodule Error : sig ... end

Extism error type

Sourceval with_plugin : (Plugin.t -> 'a) -> Plugin.t -> 'a

with_plugin f plugin uses Fun.protect to ensure that a plugin is freed when f finished executing

Sourceval extism_version : unit -> string

Returns the libextism version, not the version of the OCaml library