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 systems

  • epmd_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.