Merge pull request #2326 from bettio/updated-aliases

Add support for process aliases

Implement process aliases, so a process can hand out a reference that
works as a send target and deactivate it again once it is done with
it. This is the OTP mechanism behind request/reply patterns that must
not accept a late reply, and AtomVM had no equivalent. The series
rebases the original implementation on `release-0.7` and lands the
fixes found while reviewing it.

Highlights:

- `erlang:alias/0,1`, `erlang:unalias/1`, `erlang:monitor/3` with the
  `{alias, Mode}` option, and `spawn_opt` `{monitor, MonitorOpts}`.
- Sending to an alias from `erlang:send/2`, the send opcode and the
  JIT send path, and from a remote node over distribution.
- A new process reference term that carries the owner process id next
  to the ref ticks, with BEAM compliant ordering and
  `binary_to_term`/`term_to_binary` round tripping.
- Alias sends are posted as a mailbox signal, so a sender never walks
  the owner's monitor list and send order is preserved.
- Three pre-existing defects surfaced along the way are fixed in their
  own commits: a leaked process lock in `erlang:monitor/2,3`, a switch
  fall through in `context_demonitor`, and a dangling scheduler queue
  entry left behind by `context_destroy`.

A send addressed to a remote alias is dropped instead of being routed
over distribution, and the OTP `{tag, Term}` monitor option and the
`alias/1` `priority` option raise `unsupported`. All three are
documented.

Supersedes #2027
Closes #2027

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

CHANGELOG.md

@@ -23,6 +23,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added `"USB_SERIAL_JTAG"` peripheral to the ESP32 `uart` module on chips with a built-in
   USB-Serial-JTAG controller (C3/C5/C6/C61/H2/H21/H4/P4/S3)
 - Added support for the `safe` option in `erlang:binary_to_term/2`
+- Added support for process aliases: `erlang:alias/0,1`, `erlang:unalias/1`,
+  `erlang:monitor/3` with the `{alias, Mode}` option, `spawn_opt` `{monitor, MonitorOpts}` and
+  sending to an alias reference
 - Added xtensa JIT backend for esp32 platform
 - Added support for configuring pins and width for sdmmc on ESP32
 - Added support for map comprehensions
@@ -49,6 +52,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   for this limit
 - Replaced the `exavmlib` `Protocol` module with a small runtime shim (only `Protocol.__concat__/2`),
   saving ~31 KB of flash. ExAtomVM uses precompiled, unconsolidated protocols and continue to function normally at runtime.
+- Deprecated the C macro `REF_SIZE`: use `TERM_BOXED_REFERENCE_SHORT_SIZE` for references built
+  from ref ticks, `TERM_BOXED_REFERENCE_PROCESS_SIZE` for process references (aliases), or
+  `TERM_BOXED_REFERENCE_MAX_SIZE` to fit any reference. `REF_SIZE` still expands to the short
+  reference size, but now emits a compiler warning
 
 ### Removed
 - Removed `ahttp_client` support for obsolete line folding (RFC 9112 §5.2); folded header and

doc/src/apidocs/libatomvm/functions.rst

@@ -130,6 +130,7 @@ Functions
 .. doxygenfunction:: mailbox_next
 .. doxygenfunction:: mailbox_peek
 .. doxygenfunction:: mailbox_process_outer_list
+.. doxygenfunction:: mailbox_process_outer_list_native
 .. doxygenfunction:: mailbox_remove_message
 .. doxygenfunction:: mailbox_reset
 .. doxygenfunction:: mailbox_send

doc/src/distributed-erlang.md

@@ -325,4 +325,11 @@ RPC (remote procedure call) from Erlang/OTP to AtomVM is also supported.
 
 Shell requires several OTP standard library modules. See [the example project](https://github.com/pguyot/atomvm_shell).
 
+## Known Issues & Limitations
+
+- Sending to a remote process alias is not supported: a message sent from AtomVM to an alias
+  (a reference) of another node is silently dropped instead of being routed over distribution.
+  The other direction works: a message sent from a remote BEAM node to an alias of an AtomVM
+  process is delivered.
+
 Please do not hesitate to file issues or pull requests for additional features.

libs/estdlib/src/erlang.erl

@@ -104,6 +104,7 @@
     make_ref/0,
     send/2,
     monitor/2,
+    monitor/3,
     demonitor/1,
     demonitor/2,
     exit/1,
@@ -174,7 +175,10 @@
     tl/1,
     trunc/1,
     tuple_size/1,
-    tuple_to_list/1
+    tuple_to_list/1,
+    alias/0,
+    alias/1,
+    unalias/1
 ]).
 
 -export_type([
@@ -212,12 +216,14 @@
     | {max_heap_size, pos_integer()}
     | {atomvm_heap_growth, atomvm_heap_growth_strategy()}
     | link
-    | monitor.
+    | monitor
+    | {monitor, [monitor_option()]}.
 
 -type send_destination() ::
     pid()
     | port()
-    | atom().
+    | atom()
+    | reference().
 
 % Current type until we make these references
 -type resource() :: binary().
@@ -238,6 +244,8 @@
 -type raise_stacktrace() ::
     [{module(), atom(), arity() | [term()]} | {function(), arity() | [term()]}] | stacktrace().
 
+-type monitor_option() :: {alias, explicit_unalias | demonitor | reply_demonitor}.
+
 %%-----------------------------------------------------------------------------
 %% @param   Time time in milliseconds after which to send the timeout message.
 %% @param   Dest Pid or server name to which to send the timeout message.
@@ -1222,8 +1230,10 @@ spawn_monitor(Module, Function, Args) ->
 
 %%-----------------------------------------------------------------------------
 %% @param   Function    function to create a process from
-%% @param   Options     additional options.
-%% @returns pid of the new process
+%% @param   Options     additional options, see `spawn_option()'. With `monitor'
+%%          or `{monitor, MonitorOpts}' the new process is also monitored, see
+%%          `monitor/3' for the monitor options.
+%% @returns pid of the new process, or `{Pid, MonitorRef}' when monitoring
 %% @doc     Create a new process.
 %% @end
 %%-----------------------------------------------------------------------------
@@ -1236,8 +1246,10 @@ spawn_opt(_Name, _Options) ->
 %% @param   Module      module of the function to create a process from
 %% @param   Function    name of the function to create a process from
 %% @param   Args        arguments to pass to the function to create a process from
-%% @param   Options     additional options.
-%% @returns pid of the new process
+%% @param   Options     additional options, see `spawn_option()'. With `monitor'
+%%          or `{monitor, MonitorOpts}' the new process is also monitored, see
+%%          `monitor/3' for the monitor options.
+%% @returns pid of the new process, or `{Pid, MonitorRef}' when monitoring
 %% @doc     Create a new process by calling exported Function from Module with Args.
 %% @end
 %%-----------------------------------------------------------------------------
@@ -1277,10 +1289,11 @@ make_ref() ->
     erlang:nif_error(undefined).
 
 %%-----------------------------------------------------------------------------
-%% @param   Pid     process to send the message to
+%% @param   Target  process, registered name or alias to send the message to
 %% @param   Message message to send
 %% @returns the sent message
-%% @doc     Send a message to a given process
+%% @doc     Send a message to a given process. A message sent to a reference
+%%          that is not an active alias is silently dropped.
 %% @end
 %%-----------------------------------------------------------------------------
 -spec send(Target :: send_destination(), Message :: Message) -> Message.
@@ -1306,6 +1319,32 @@ send(_Target, _Message) ->
 monitor(_Type, _PidOrPort) ->
     erlang:nif_error(undefined).
 
+%%-----------------------------------------------------------------------------
+%% @param   Type        type of monitor to create
+%% @param   PidOrPort   pid or port of the object to monitor
+%% @param   Options     monitor options
+%% @returns a monitor reference
+%% @doc     Creates a monitor and allows passing additional options.
+%%          Currently, only the `{alias, AliasMode}' option is supported. Passing it
+%%          makes the monitor also an alias on the calling process (see `alias/0').
+%%          `AliasMode' defines the behaviour of the alias:
+%%          - explicit_unalias - the alias can be only removed with `unalias/1',
+%%          - demonitor - the alias is also removed when the monitor is removed,
+%%                        by `demonitor/1' or by the delivery of a `DOWN' message,
+%%          - reply_demonitor - additionally, the alias is deactivated and the
+%%                              monitor removed (as by `demonitor/1') when the
+%%                              first message sent via the alias is delivered.
+%%
+%%          <b>Note:</b> Unlike Erlang/OTP, the `{tag, Term}' option is not
+%%          supported and raises `unsupported'.
+%% @end
+%%-----------------------------------------------------------------------------
+-spec monitor
+    (Type :: process, Pid :: pid() | atom(), [monitor_option()]) -> reference();
+    (Type :: port, Port :: port() | atom(), [monitor_option()]) -> reference().
+monitor(_Type, _PidOrPort, _Options) ->
+    erlang:nif_error(undefined).
+
 %%-----------------------------------------------------------------------------
 %% @param   Monitor reference of monitor to remove
 %% @returns `true'
@@ -2147,3 +2186,41 @@ tuple_size(_Tuple) ->
 -spec tuple_to_list(Tuple :: tuple()) -> [term()].
 tuple_to_list(_Tuple) ->
     erlang:nif_error(undefined).
+
+%%-----------------------------------------------------------------------------
+%% @returns A reference aliasing the calling process.
+%% @doc     Creates an alias for the calling process. The alias can be used
+%%          to send messages to the process like the PID. The alias can also be
+%%          created along with a monitor - see `monitor/3'. The alias can be
+%%          removed by calling `unalias/1'.
+%% @end
+%%-----------------------------------------------------------------------------
+-spec alias() -> Alias when Alias :: reference().
+alias() ->
+    erlang:nif_error(undefined).
+
+%%-----------------------------------------------------------------------------
+%% @param   Options alias options
+%% @returns A reference aliasing the calling process.
+%% @doc     Creates an alias for the calling process, like `alias/0'.
+%%          With `explicit_unalias' (the default, so `alias([])' is `alias/0')
+%%          the alias stays active until `unalias/1'; with `reply' it is
+%%          deactivated when the first message sent via the alias is delivered.
+%%
+%%          <b>Note:</b> Unlike Erlang/OTP, the `priority' option (OTP 28) is
+%%          not supported and raises `unsupported'.
+%% @end
+%%-----------------------------------------------------------------------------
+-spec alias(Options) -> Alias when Options :: [explicit_unalias | reply], Alias :: reference().
+alias(_Options) ->
+    erlang:nif_error(undefined).
+
+%%-----------------------------------------------------------------------------
+%% @param   Alias the alias to be removed.
+%% @returns `true' if alias was removed, `false' if it was not found
+%% @doc     Removes process alias. See `alias/0' for more information.
+%% @end
+%%-----------------------------------------------------------------------------
+-spec unalias(Alias) -> boolean() when Alias :: reference().
+unalias(_Alias) ->
+    erlang:nif_error(undefined).