Working with guest VMs

Copy Markdown View Source
Mix.install([{:kettlecorn, "~> 0.1.0"}])

About this notebook

Use a running VM for Erlang evaluation, GenServer calls, messages, and host calls. Examine how returned guest values differ from host values. Start with Getting started for installation, evaluation, isolation, and resource limits.

Requires Elixir 1.20 or later on x86_64 or ARM64 Linux or Apple silicon macOS. Run the cells in order.

{:ok, runtime} = Kettlecorn.Install.runtime()

Start a VM

The VM has a ten-minute lifetime for this interactive session. Restart from this cell if it expires. owner: self() sends guest messages and host calls to this process; host applications must keep consuming these events.

{:ok, vm} =
  Kettlecorn.start_link(
    owner: self(),
    max_memory: 256 * 1024 * 1024,
    max_fuel: 1_000_000_000_000,
    max_lifetime: 600_000
  )

GenServers in the guest

Kettlecorn.call/4 and Kettlecorn.cast/3 reach GenServers registered in the guest:

{:ok, _} =
  Kettlecorn.eval(vm, """
  defmodule Counter do
    use GenServer
    def init(n), do: {:ok, n}
    def handle_call(:get, _from, n), do: {:reply, n, n}
    def handle_cast({:add, k}, n), do: {:noreply, n + k}
  end

  GenServer.start(Counter, 0, name: :counter)
  """)

:ok = Kettlecorn.cast(vm, :counter, {:add, 5})
{:ok, 5} = Kettlecorn.call(vm, :counter, :get)

Calling an unregistered name returns an error:

{:error, :noproc} = Kettlecorn.call(vm, :nobody, :get)

Messages

The guest sends messages to the host with Kettlecorn.Host.send/1. They arrive at the owner as {:kettlecorn, vm, {:message, term}}. The owner acknowledges each event after handling it to release its delivery budget. The host sends {:wasm, payload} to a guest process with Kettlecorn.send/4:

{:ok, _} =
  Kettlecorn.eval(vm, """
  echo = spawn(fn ->
    receive do
      {:wasm, {:ping, n}} -> Kettlecorn.Host.send({:pong, n * 2})
    end
  end)

  Process.register(echo, :echo)
  """)

:ok = Kettlecorn.send(vm, :echo, {:ping, 21})

receive do
  {:kettlecorn, ^vm, {:message, message}} ->
    Kettlecorn.acknowledge(vm)
    message
after
  5_000 -> :timeout
end

Host calls

A host call lets the guest ask the host for something it can't do itself. The guest calls Kettlecorn.Host.call/3 and waits; the owner gets {:host_call, reply_to, name, args} and answers with Kettlecorn.reply/3:

task = Task.async(fn -> Kettlecorn.eval(vm, ~S|Kettlecorn.Host.call("double", %{n: 21})|) end)

receive do
  {:kettlecorn, ^vm, {:host_call, reply_to, "double", %{n: n}}} when is_number(n) ->
    Kettlecorn.reply(vm, reply_to, {:ok, n * 2})
    Kettlecorn.acknowledge(vm)
after
  5_000 -> raise "guest did not request double"
end

{:ok, %{"value" => {:ok, 42}}} = Task.await(task)

Returned guest values

Everything from the guest is decoded by Kettlecorn.ETF, which never creates atoms or live pids on the host. An atom the host doesn't have arrives as {:unknown_atom, name} and a guest pid as a Kettlecorn.Pid that only addresses the guest. A struct whose module atom exists on the host becomes Kettlecorn.Struct, holding its module and fields. Unknown module atoms remain {:unknown_atom, name} in ordinary maps:

{:ok,
 %{
   "value" => %Kettlecorn.Struct{
     module: Date,
     fields: %{calendar: Calendar.ISO, year: year, month: month, day: day}
   }
 }} =
  Kettlecorn.eval(vm, "Date.utc_today()")

{:ok, date} = Date.new(year, month, day)
date

The example accepts an ISO date and reconstructs it with Date.new/3, which validates its fields. Before constructing host structs, check the module and field values: their protocol implementations run on the host. The Validating guest data notebook shows validation for nested guest values.

Erlang

With language: :erlang, Kettlecorn.eval/3 evaluates Erlang. Expressions run one after another, as in the Erlang shell, and bindings are Erlang variables:

{:ok, %{"value" => 120, "output" => "5! = 120\n"}} =
  Kettlecorn.eval(
    vm,
    ~S|Fact = fun F(0) -> 1; F(K) -> K * F(K - 1) end. R = Fact(N), io:format("~p! = ~p~n", [N, R]). R|,
    language: :erlang,
    binding: %{"N" => 5}
  )

Source that starts with -module(name). is a module. It's compiled and loaded, and both languages can call it:

{:ok, %{"value" => {:module, :shapes}}} =
  Kettlecorn.eval(
    vm,
    ~S"""
    -module(shapes).
    -export([area/1]).

    area({circle, R}) -> math:pi() * R * R;
    area({rect, W, H}) -> W * H.
    """,
    language: :erlang
  )

{:ok, %{"value" => 12}} = Kettlecorn.eval(vm, ":shapes.area({:rect, 3, 4})")

Results are inspected and errors formatted as Erlang does:

{:error, %{"message" => message}} = Kettlecorn.eval(vm, "shapes:area(square).", language: :erlang)
IO.puts(message)

Stop the VM

Kettlecorn.stop(vm)

Use cases builds services around these APIs. The Guest API guide lists the guest messaging and HTTP contracts; Kettlecorn documents the host functions.