Wasmex.Components.GuestResource (wasmex v0.15.1)

Copy Markdown

Guest-owned WebAssembly component resources.

A resource is a handle tied to the Store and component instance that created it. Calls are serialized by that Store, so the handle can be shared between processes without an additional owner process.

For an arity-aware API, generate a module from WIT:

defmodule Counter do
  use Wasmex.Components.GuestResource,
    wit: File.read!("counter.wit"),
    resource: "counter"
end

{:ok, counter} = Counter.new(instance, 42)
{:ok, 43} = Counter.increment(counter)
:ok = Counter.drop(counter)

Generated functions accept a final keyword list with a :timeout option. Constructors and static functions accept either a Wasmex.Components server or a low-level Wasmex.Components.Instance; methods accept a resource handle. Set the macro's :world option when the WIT defines multiple worlds.

Resource handles that are not explicitly dropped have a best-effort native finalizer. Passing a handle to an own<T> parameter moves it; later calls with that handle return an error.

A timeout interrupts Wasmtime execution and can invalidate that component instance. Discard the instance after any timed-out constructor, call, or drop.

Summary

Types

function_kind()
static_function_kind()
t()

Functions

call(resource, kind, function_name, params \\ [], timeout \\ 5000)

Calls a guest resource method.

call_static(instance_or_server, resource_path, kind, function_name, params \\ [], timeout \\ 5000)

Calls a static function associated with a guest resource type.

drop(guest_resource, timeout \\ 5000)

Explicitly releases a guest resource.

new(instance_or_server, resource_path, params \\ [], timeout \\ 5000)

Calls an exported guest resource constructor.

Types

function_kind()

@type function_kind() :: :method | :async_method

static_function_kind()

@type static_function_kind() :: :static | :async_static

t()

@type t() :: %Wasmex.Components.GuestResource{
  reference: reference(),
  resource: binary()
}

Functions

call(resource, kind, function_name, params \\ [], timeout \\ 5000)

@spec call(t(), function_kind(), String.t() | atom(), list(), timeout()) ::
  :ok | {:ok, any()} | {:error, any()}

Calls a guest resource method.

call_static(instance_or_server, resource_path, kind, function_name, params \\ [], timeout \\ 5000)

@spec call_static(
  Wasmex.Components.Instance.t() | GenServer.server(),
  Wasmex.Components.function_name_or_path(),
  static_function_kind(),
  String.t() | atom(),
  list(),
  timeout()
) :: :ok | {:ok, any()} | {:error, any()}

Calls a static function associated with a guest resource type.

Static functions take a component instance rather than a resource handle and remain callable when no live handle exists.

drop(guest_resource, timeout \\ 5000)

@spec drop(t(), timeout()) :: :ok | {:error, any()}

Explicitly releases a guest resource.

Dropping an already-dropped handle succeeds. Methods called afterwards return an error.

new(instance_or_server, resource_path, params \\ [], timeout \\ 5000)

@spec new(
  Wasmex.Components.Instance.t() | GenServer.server(),
  Wasmex.Components.function_name_or_path(),
  list(),
  timeout()
) :: {:ok, t()} | {:error, any()}

Calls an exported guest resource constructor.

The resource path consists of the exported interface path followed by the WIT resource name.