Getting started

Every example on this page is a file in examples/ of the repository, and the tests run each of them against real Erlang nodes of every supported release. The Erlang side is always a shell started like this:

erl -name erl@127.0.0.1 -setcookie COOKIE

Start a node, send a message

A Node is created inside a running event loop. await node.wait_started() returns when it listens and is registered in EPMD, and raises if that failed. node.destroy() closes everything.

"""Send one message from Python to a registered Erlang process.

1. ``erl -name erl@127.0.0.1 -setcookie COOKIE``
2. In the Erlang shell: ``register(shell, self()).``
3. ``python examples/e01_send_to_erlang.py``
4. In the Erlang shell: ``flush().`` prints ``Shell got hello``.
"""

import asyncio

from term import Atom

from pyrlang.node import Node


async def main(
    node_name: str = "py@127.0.0.1",
    peer: str = "erl@127.0.0.1",
    cookie: str = "COOKIE",
) -> None:
    # A node is created inside a running event loop.
    node = Node(node_name=node_name, cookie=cookie)
    try:
        # Listening, and registered in EPMD.
        await node.wait_started()
        # The connection is made by the first message to that node. A
        # registered name on another node is addressed as (Node, Name).
        await node.send(
            sender=None,
            receiver=(Atom(peer), Atom("shell")),
            message=Atom("hello"),
        )
    finally:
        node.destroy()


if __name__ == "__main__":
    asyncio.run(main())

send() takes as the receiver:

  • a pid (Pid), local or on another node;

  • an Atom: a name registered on this node;

  • a tuple (Node, Name): a name registered on another node (Erlang writes the same address the other way round, {Name, Node});

  • a Reference: a process alias.

The first message to a node sets up the connection. await node.send(...) waits for that and raises when the node cannot be reached (NodeException if EPMD does not know it, EPMDConnectionError if EPMD cannot be asked, DistributionError if the handshake fails, for example over a wrong cookie). send_nowait() does not wait and can be called from code that is not a coroutine: the message is delivered or queued when it returns, and one to a node that turns out to be unreachable is dropped and logged.

Erlang can also start the connection: net_adm:ping('py@127.0.0.1')., or simply a message to a Python process.

Processes

A Process has a pid, an inbox, and optionally a registered name. Erlang sends to it as to any process. Override handle_one_inbox_message:

"""A Python process with a registered name that answers messages.

1. ``python examples/e02_registered_process.py`` (runs until interrupted)
2. ``erl -name erl@127.0.0.1 -setcookie COOKIE``
3. In the Erlang shell::

       {my_process, 'py@127.0.0.1'} ! {self(), <<"hi">>}.
       flush().

   prints ``Shell got {echo,<<"hi">>}``.

While the node runs, Erlang can also call Python functions on it::

       rpc:call('py@127.0.0.1', math, sqrt, [16.0]).
"""

import asyncio
from typing import Any

from term import Atom

from pyrlang.node import Node
from pyrlang.process import Process


class MyProcess(Process):
    def __init__(self) -> None:
        super().__init__()
        self.get_node().register_name(self, Atom("my_process"))

    def handle_one_inbox_message(self, msg: Any) -> None:
        # A message carries no sender: Erlang puts self() into the message.
        if isinstance(msg, tuple) and len(msg) == 2:
            sender, text = msg
            self.get_node().send_nowait(
                sender=self.pid_, receiver=sender, message=(Atom("echo"), text)
            )


async def main(node_name: str = "py@127.0.0.1", cookie: str = "COOKIE") -> None:
    node = Node(node_name=node_name, cookie=cookie)
    try:
        await node.wait_started()
        MyProcess()
        await asyncio.Event().wait()  # serve until cancelled
    finally:
        node.destroy()


if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        pass

A message carries no sender, as in Erlang: the sender puts its pid into the message when it wants an answer.

Process(passive=True) has no inbox task: its handler is called straight from the connection that received the message, which is cheaper, and the handler must not block. A passive process may override handle_message_from() instead and gets the sender’s pid where the protocol carries it.

A process ends when:

  • it calls its own exit();

  • somebody calls exit_process() with its pid, or Erlang calls exit(Pid, Reason);

  • a process it is linked to ends with a reason other than normal, or the connection to that process’s node is lost.

The node holds a reference to every live process, so a process that is no longer needed has to exit to be freed.

gen_server

A GenServer answers gen_server:call and gen_server:cast from Erlang. Handlers are methods marked with call(), cast() and info():

"""A Python process that answers ``gen_server:call`` and ``gen_server:cast``.

1. ``python examples/e03_gen_server.py`` (runs until interrupted)
2. ``erl -name erl@127.0.0.1 -setcookie COOKIE``
3. In the Erlang shell::

       Counter = {counter, 'py@127.0.0.1'}.
       gen_server:call(Counter, {add, 5}).    % ok
       gen_server:call(Counter, get).         % 5
       gen_server:cast(Counter, reset).
       gen_server:call(Counter, get).         % 0
"""

import asyncio
from typing import Any

from term import Atom

from pyrlang.gen.decorators import call, cast
from pyrlang.gen.gen_server import GenServer
from pyrlang.node import Node


def _is_add(msg: Any) -> bool:
    return isinstance(msg, tuple) and len(msg) == 2 and msg[0] == Atom("add")


class Counter(GenServer):
    def __init__(self) -> None:
        super().__init__()
        self.count = 0
        self.get_node().register_name(self, Atom("counter"))

    # A request goes to the handler with the lowest number whose pattern
    # (a function of the request) is true, like the clauses of handle_call.
    @call(1, lambda msg: msg == Atom("get"))
    def get(self, msg: Any) -> int:
        return self.count  # the return value is the reply

    @call(2, _is_add)
    def add(self, msg: Any) -> Atom:
        self.count += msg[1]
        return Atom("ok")

    @cast(1, lambda msg: msg == Atom("reset"))
    def reset(self, msg: Any) -> None:
        self.count = 0


async def main(node_name: str = "py@127.0.0.1", cookie: str = "COOKIE") -> None:
    node = Node(node_name=node_name, cookie=cookie)
    try:
        await node.wait_started()
        Counter()
        await asyncio.Event().wait()  # serve until cancelled
    finally:
        node.destroy()


if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        pass

A handler may be an async def. From Python, GenServerInterface makes calls and casts to a gen_server given its pid.

Processes spawned from Erlang

"""Let Erlang spawn Python processes.

1. ``python examples/e05_spawn_from_erlang.py`` (runs until interrupted)
2. ``erl -name erl@127.0.0.1 -setcookie COOKIE``
3. In the Erlang shell::

       Pid = spawn('py@127.0.0.1', workers, doubler, [self()]).
       Pid ! 21.
       flush().

   prints ``Shell got 42``. ``spawn_link``, ``spawn_monitor`` and
   ``spawn_request`` work the same way.
"""

import asyncio
from typing import Any

from term import Pid

from pyrlang.node import Node
from pyrlang.process import Process


class Doubler(Process):
    """Sends twice each number it gets to the process that asked for it."""

    def __init__(self, reply_to: Pid) -> None:
        super().__init__()
        self.reply_to = reply_to

    def handle_one_inbox_message(self, msg: Any) -> None:
        if isinstance(msg, int):
            self.get_node().send_nowait(
                sender=self.pid_, receiver=self.reply_to, message=2 * msg
            )


async def main(node_name: str = "py@127.0.0.1", cookie: str = "COOKIE") -> None:
    node = Node(node_name=node_name, cookie=cookie)
    try:
        await node.wait_started()
        # spawn(Node, workers, doubler, Args) calls Doubler(*Args).
        node.register_spawnable("workers", "doubler", Doubler)
        await asyncio.Event().wait()  # serve until cancelled
    finally:
        node.destroy()


if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        pass

Calling Python functions

Any running node answers rpc:call and erpc:call; nothing has to be registered. See Calling Python from Erlang.