Distributed Erlang
For a generic introduction to Distributed Erlang Systems, please refer to the dedicated section of Erlang/OTP documentation.
AtomVM provides an implementation of Erlang distribution protocol and AtomVM nodes can take part in clusters with both AtomVM and BEAM nodes.
Distribution is currently available on all platforms with TCP/IP communication, namely:
Generic Unix
ESP32
RP2 (Pico)
Two examples are provided:
disterl in
examples/erlang/disterl.erl
: distribution on Unix systemsepmd_disterl in
examples/esp32/epmd_disterl.erl
: distribution on ESP32 devices
Starting and stopping distribution
Distribution has to be started programmatically. Following Erlang/OTP, distribution relies on kernel
which needs to be started.
The following lines will start distribution on Unix systems with long name atomvm@127.0.0.1
.
{ok, _KernelPid} = kernel:start(normal, []),
{ok, _NetKernelPid} = net_kernel:start('atomvm@127.0.0.1', #{name_domain => longnames}),
ok = net_kernel:set_cookie(<<"AtomVM">>).
net_kernel:stop/0
can be used to stop distribution.
epmd
AtomVM nodes can use Erlang/OTP’s epmd on Unix systems. AtomVM is also bundled with a pure Erlang implementation of epmd
which can be used on all platforms. Module is called epmd
, to be distinguished from erl_epmd
which is the client.
AtomVM’s epmd daemon can be started with:
{ok, _EPMDPid} = epmd:start_link([]).
This has to be called before invoking net_kernel:start/2
.
Erlang/OTP compatibility
AtomVM can connect to Erlang/OTP 24 and higher.
Security
AtomVM supports cookie authentication. However, distribution over TLS is not supported yet.
Alternative carrier
Following Erlang/OTP, AtomVM supports alternative carriers with distribution modules. Please refer to Erlang/OTP’s dedicated documentation.
The main difference is that packets exchanged by f_recv
and f_send
handlers must be binaries instead of list of integers, for memory usage reasons.
AtomVM’s f_send
has the following signature:
fun (DistCtrlr, Data :: binary()) -> ok | {error, Error}
AtomVM’s f_recv
has the following signature:
fun (DistCtrlr, Length :: pos_integer(), Timeout :: timeout()) -> {ok, Packet} | {error, Reason}
AtomVM’s distribution is based on socket_dist
and socket_dist_controller
modules which can also be used with BEAM by definining BEAM_INTERFACE
to adjust for the difference.
Distribution features
Distribution implementation is (very) partial. The most basic features are available:
serialization of all types
epmd protocol (client and server)
message passing
monitoring processes
I/O distribution (“group leader”).
RPC (remote procedure call) from Erlang/OTP to AtomVM is also supported. Shell is not supported yet.
Please do not hesitate to file issues or pull requests for additional features.