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
endHost 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)
dateThe 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.