Merge pull request #1641 from feature/distributed-erlang

Distributed Erlang

Despite the title, this PR introduces countless improvements.
Some manual updates to 3rd party NIFs and components are expected, but
most of existing code should continue to work.

These changes are made under both the "Apache 2.0" and the "GNU Lesser General
Public License 2.1 or later" license terms (dual license).

SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later

Author: bettio

.github/workflows/run-tests-with-beam.yaml

@@ -142,7 +142,7 @@ jobs:
       working-directory: build
       run: |
         export PATH="${{ matrix.path_prefix }}$PATH"
-        erl -pa tests/libs/estdlib/ -pa tests/libs/estdlib/beams/ -pa libs/etest/src/beams -s tests -s init stop -noshell
+        erl -pa tests/libs/estdlib/ -pa tests/libs/estdlib/beams/ -pa libs/etest/src/beams -pa libs/eavmlib/src/beams -s tests -s init stop -noshell
 
     # Test
     - name: "Run tests/libs/etest/test_eunit with OTP eunit"

CHANGELOG.md

@@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Added a limited implementation of the OTP `ets` interface
 - Added `code:all_loaded/0` and `code:all_available/0`
+- Added `erlang:split_binary/2`
+- Added `inet:getaddr/2`
+- Added support for external pids and encoded pids in external terms
+- Added support for external refs and encoded refs in external terms
+- Introduce ports to represent native processes and added support for external ports and encoded ports in external terms
+- Added `atomvm:get_creation/0`, equivalent to `erts_internal:get_creation/0`
 - Added menuconfig option for enabling USE_USB_SERIAL, eg. serial over USB for certain ESP32-S2 boards etc.
 - Partial support for `erlang:fun_info/2`
 - Added support for `registered_name` in `erlang:process_info/2` and `Process.info/2`
@@ -19,6 +25,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added `esp:partition_read/3`, and documentation for `esp:partition_erase_range/2/3` and `esp:partition_write/3`
 - Added support for list insertion in 'ets:insert/2'.
 - Support to OTP-28
+- Added `atomvm:subprocess/4` to perform pipe/fork/execve on POSIX platforms
+- Added `externalterm_to_term_with_roots` to efficiently preserve roots when allocating memory for external terms.
+- Added `erl_epmd` client implementation to epmd using `socket` module
+- Added support for socket asynchronous API for `recv`, `recvfrom` and `accept`.
+- Added support for UDP multicast with socket API.
 - Added support for `ets:update_counter/3` and `ets:update_counter/4`.
 - Added `erlang:+/1`
 - Added `lists:append/1` and `lists:append/2`
@@ -33,10 +44,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added `code:is_loaded/1` and `code:which/1`
 - Added several `io_lib` functions including `io_lib:fwrite/2` and `io_lib:write_atom/1`
 - Added `init:get_argument/1`, `init:get_plain_arguments/0` and `init:notify_when_started/1`
+- Added `application:get_env/2`
 - Added CodeQL analysis to esp32, stm32, pico, and wasm workflows
 
+### Changed
+
+- Removed `externalterm_to_term_copy` added in [0.6.5] and introduced flags to `externalterm_to_term` to perform copy.
+
 ### Fixed
+
 - ESP32: improved sntp sync speed from a cold boot.
+- Fixed `gen_server` internal messages to match OTP so it works across erlang distribution
 - Utilize reserved `phy_init` partition on ESP32 to store wifi calibration for faster connections.
 - Support for zero count in `lists:duplicate/2`.
 - packbeam: fix memory leak preventing building with address sanitizer

UPDATING.md

@@ -6,6 +6,14 @@
 
 # AtomVM Update Instructions
 
+## v0.6.6 -> Unreleased
+- Ports now represent the native processes. Port drivers should return a port (instead of a pid),
+by using `term_port_from_local_process_id` instead of `term_from_local_process_id`. Sockets, from
+port socket driver, are also represented by a port and some matching code may need to be updated from
+`is_pid/1` to `is_port/1`.
+- Ports and pids can be registered. Function `globalcontext_get_registered_process` result now is
+a term that can be a `port()` or a `pid()`.
+
 ## v0.6.4 -> v0.6.5
 
 - ESP32: `esp32boot.avm` doesn't contain anymore Elixir standard library, use instead

doc/src/distributed-erlang.md

@@ -0,0 +1,88 @@
+<!--
+ Copyright 2025 Paul Guyot <pguyot@kallisys.net>
+ SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
+-->
+
+# Distributed Erlang
+
+For a generic introduction to Distributed Erlang Systems, please refer to the [dedicated section](https://www.erlang.org/doc/system/distributed.html) 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`.
+
+```erlang
+{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:
+
+```erlang
+{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](https://www.erlang.org/doc/apps/erts/alt_dist#distribution-module).
+
+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:
+
+```erlang
+fun (DistCtrlr, Data :: binary()) -> ok | {error, Error}
+```
+
+AtomVM's `f_recv` has the following signature:
+
+```erlang
+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.

doc/src/index.rst

@@ -28,6 +28,7 @@ AtomVM includes many advanced features, including process spawning, monitoring,
    atomvm-tooling.md
    programmers-guide
    network-programming-guide
+   distributed-erlang
    build-instructions
    atomvm-internals
    memory-management

examples/emscripten/CMakeLists.txt

@@ -25,4 +25,5 @@ include(BuildErlang)
 pack_runnable(run_script run_script estdlib eavmlib)
 pack_runnable(call_cast call_cast eavmlib)
 pack_runnable(html5_events html5_events estdlib eavmlib)
+pack_runnable(echo_websocket echo_websocket estdlib eavmlib)
 pack_runnable(wasm_webserver wasm_webserver estdlib eavmlib)

examples/emscripten/echo_websocket.erl

@@ -0,0 +1,164 @@
+%
+% This file is part of AtomVM.
+%
+% Copyright 2025 Paul Guyot <pguyot@kallisys.net>
+%
+% Licensed under the Apache License, Version 2.0 (the "License");
+% you may not use this file except in compliance with the License.
+% You may obtain a copy of the License at
+%
+%    http://www.apache.org/licenses/LICENSE-2.0
+%
+% Unless required by applicable law or agreed to in writing, software
+% distributed under the License is distributed on an "AS IS" BASIS,
+% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+% See the License for the specific language governing permissions and
+% limitations under the License.
+%
+% SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
+%
+
+-module(echo_websocket).
+-export([start/0]).
+
+-define(ECHO_WEBSOCKET_URL, <<"wss://echo.websocket.org">>).
+
+start() ->
+    register(main, self()),
+    Supported = websocket:is_supported(),
+    if
+        Supported ->
+            emscripten:run_script(
+                [
+                    <<"window.document.getElementById('supported').innerHTML = 'yes';">>,
+                    <<"window.document.getElementById('send-button').onclick = () => { Module.cast('main', window.document.getElementById('send-text').value); };">>
+                ],
+                [main_thread, async]
+            ),
+            websocket_loop();
+        true ->
+            emscripten:run_script(
+                [
+                    <<"window.document.getElementById('supported').innerHTML = 'no';">>
+                ],
+                [main_thread, async]
+            )
+    end.
+
+websocket_loop() ->
+    Websocket = websocket:new(?ECHO_WEBSOCKET_URL),
+    websocket_loop(Websocket).
+
+websocket_loop(Websocket) ->
+    ReadyState = websocket:ready_state(Websocket),
+    URL = websocket:url(Websocket),
+    Protocol = websocket:protocol(Websocket),
+    Extensions = websocket:extensions(Websocket),
+    emscripten:run_script(
+        [
+            <<"window.document.getElementById('ready-state').innerHTML = '">>,
+            atom_to_list(ReadyState),
+            <<"';">>,
+            <<"window.document.getElementById('url').innerHTML = '">>,
+            URL,
+            <<"';">>,
+            <<"window.document.getElementById('protocol').innerHTML = '">>,
+            Protocol,
+            <<"';">>,
+            <<"window.document.getElementById('extensions').innerHTML = '">>,
+            Extensions,
+            <<"';">>
+        ],
+        [main_thread, async]
+    ),
+    receive
+        {emscripten, {cast, Message}} ->
+            emscripten:run_script(
+                [
+                    <<"const e = window.document.createElement('div');">>,
+                    <<"e.classList.add('client-msg');">>,
+                    <<"e.append(\"">>,
+                    escape_js_str(binary_to_list(Message)),
+                    <<"\");">>,
+                    <<"window.document.getElementById('transcript').appendChild(e);">>
+                ],
+                [main_thread, async]
+            ),
+            ok = websocket:send_binary(Websocket, Message),
+            websocket_loop(Websocket);
+        {websocket_open, Websocket} ->
+            emscripten:run_script(
+                [
+                    <<"window.document.getElementById('send-text').disabled = false;">>,
+                    <<"window.document.getElementById('send-button').disabled = false;">>
+                ],
+                [main_thread, async]
+            ),
+            websocket_loop(Websocket);
+        {websocket, Websocket, Data} ->
+            emscripten:run_script(
+                [
+                    <<"const e = window.document.createElement('div');">>,
+                    <<"e.classList.add('server-msg');">>,
+                    <<"e.append(\"">>,
+                    escape_js_str(binary_to_list(Data)),
+                    <<"\");">>,
+                    <<"window.document.getElementById('transcript').appendChild(e);">>
+                ],
+                [main_thread, async]
+            ),
+            websocket_loop(Websocket);
+        {websocket_error, Websocket} ->
+            emscripten:run_script(
+                [
+                    <<"window.document.getElementById('send-text').disabled = false;">>,
+                    <<"window.document.getElementById('send-button').disabled = false;">>,
+                    <<"const e = window.document.createElement('div');">>,
+                    <<"e.classList.add('error-msg');">>,
+                    <<"e.append('Error');">>,
+                    <<"window.document.getElementById('transcript').appendChild(e);">>
+                ],
+                [main_thread, async]
+            );
+        {websocket_closed, Websocket, {WasClean, Code, Reason}} ->
+            emscripten:run_script(
+                [
+                    <<"window.document.getElementById('send-text').disabled = true;">>,
+                    <<"window.document.getElementById('send-button').disabled = true;">>,
+                    <<"const e = window.document.createElement('div');">>,
+                    <<"e.classList.add('close-msg');">>,
+                    <<"const wasClean = window.document.createElement('p');">>,
+                    <<"wasClean.append(\"">>,
+                    atom_to_list(WasClean),
+                    <<"\");">>,
+                    <<"e.appendChild(wasClean);">>,
+                    <<"const code = window.document.createElement('p');">>,
+                    <<"code.append(\"">>,
+                    integer_to_list(Code),
+                    <<"\");">>,
+                    <<"e.appendChild(code);">>,
+                    <<"const reason = window.document.createElement('p');">>,
+                    <<"reason.append(\"">>,
+                    escape_js_str(binary_to_list(Reason)),
+                    <<"\");">>,
+                    <<"e.appendChild(reason);">>,
+                    <<"window.document.getElementById('transcript').appendChild(e);">>
+                ],
+                [main_thread, async]
+            );
+        Other ->
+            io:format("Unexpected message ~p\n", [Other]),
+            websocket_loop(Websocket)
+    end.
+
+escape_js_str(Str) ->
+    escape_js_str(Str, []).
+
+escape_js_str([$" | Tail], Acc) ->
+    escape_js_str(Tail, ["\\\"" | Acc]);
+escape_js_str([$\n | Tail], Acc) ->
+    escape_js_str(Tail, ["<br />" | Acc]);
+escape_js_str([C | Tail], Acc) ->
+    escape_js_str(Tail, [C | Acc]);
+escape_js_str([], Acc) ->
+    lists:reverse(Acc).