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 callsexit(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.
Links and monitors¶
monitor_process() and
link() work on local and remote pids, and
Erlang’s monitor/2 and link/1 work on Python pids.
"""Monitor an Erlang process and link to another from Python.
1. ``erl -name erl@127.0.0.1 -setcookie COOKIE``
2. In the Erlang shell::
register(shell, self()).
Sleep = fun() -> receive stop -> ok end end.
Monitored = spawn(Sleep), Linked = spawn(Sleep).
3. ``python examples/e04_link_monitor.py``, which asks ``shell`` for pids.
4. In the Erlang shell::
receive {pids_please, Py} -> Py ! {Monitored, Linked} end.
exit(Monitored, kill), exit(Linked, some_reason).
The Python side prints the ``DOWN`` message of the monitor and the exit
reason that reached the linked process.
"""
import asyncio
from typing import Any
from term import Atom
from pyrlang.node import Node
from pyrlang.process import Process
class Watcher(Process):
"""Collects what arrives; ``exit`` runs when an exit signal ends it."""
def __init__(self) -> None:
super().__init__()
self.messages: asyncio.Queue[Any] = asyncio.Queue()
self.exit_reason: asyncio.Future[Any] = asyncio.Future()
def handle_one_inbox_message(self, msg: Any) -> None:
self.messages.put_nowait(msg)
def exit(self, reason: Any = None) -> None:
if not self.exit_reason.done():
self.exit_reason.set_result(reason)
super().exit(reason)
async def main(
node_name: str = "py@127.0.0.1",
peer: str = "erl@127.0.0.1",
cookie: str = "COOKIE",
) -> tuple[Any, Any]:
node = Node(node_name=node_name, cookie=cookie)
try:
await node.wait_started()
monitoring, linking = Watcher(), Watcher()
await node.send(
sender=monitoring.pid_,
receiver=(Atom(peer), Atom("shell")),
message=(Atom("pids_please"), monitoring.pid_),
)
monitored, linked = await monitoring.messages.get()
# When the monitored process ends, the monitoring one gets
# ('DOWN', Reference, 'process', Pid, Reason) as a message.
node.monitor_process(origin_pid=monitoring.pid_, target=monitored)
# A link is symmetric: when either process ends with a reason other
# than normal, the other one gets an exit signal and ends too.
await node.link(linking.pid_, linked)
down = await monitoring.messages.get()
print("monitor:", down)
reason = await linking.exit_reason
print("link: exited with", reason)
return down, reason
finally:
node.destroy()
if __name__ == "__main__":
asyncio.run(main())
When the connection to a node is lost, every monitor of a process there
fires with the reason noconnection, and every link to one breaks with it,
as in Erlang.
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.