# 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: ```sh erl -name erl@127.0.0.1 -setcookie COOKIE ``` ## Start a node, send a message A {py:class}`~pyrlang.node.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. ```{literalinclude} ../../examples/e01_send_to_erlang.py :language: python ``` {py:meth}`~pyrlang.node.Node.send` takes as the receiver: - a pid ({py:class}`~term.pid.Pid`), local or on another node; - an {py:class}`~term.atom.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 {py:class}`~term.reference.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 ({py:exc}`~pyrlang.errors.NodeException` if EPMD does not know it, {py:exc}`~pyrlang.errors.EPMDConnectionError` if EPMD cannot be asked, {py:exc}`~pyrlang.errors.DistributionError` if the handshake fails, for example over a wrong cookie). {py:meth}`~pyrlang.node.Node.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 {py:class}`~pyrlang.process.Process` has a pid, an inbox, and optionally a registered name. Erlang sends to it as to any process. Override `handle_one_inbox_message`: ```{literalinclude} ../../examples/e02_registered_process.py :language: python ``` 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 {py:meth}`~pyrlang.process.Process.handle_message_from` instead and gets the sender's pid where the protocol carries it. A process ends when: - it calls its own {py:meth}`~pyrlang.process.Process.exit`; - somebody calls {py:meth}`~pyrlang.node.Node.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 {py:class}`~pyrlang.gen.gen_server.GenServer` answers `gen_server:call` and `gen_server:cast` from Erlang. Handlers are methods marked with {py:func}`~pyrlang.gen.decorators.call`, {py:func}`~pyrlang.gen.decorators.cast` and {py:func}`~pyrlang.gen.decorators.info`: ```{literalinclude} ../../examples/e03_gen_server.py :language: python ``` A handler may be an `async def`. From Python, {py:class}`~pyrlang.gen.gen_server.GenServerInterface` makes calls and casts to a `gen_server` given its pid. ## Links and monitors {py:meth}`~pyrlang.node.Node.monitor_process` and {py:meth}`~pyrlang.node.Node.link` work on local and remote pids, and Erlang's `monitor/2` and `link/1` work on Python pids. ```{literalinclude} ../../examples/e04_link_monitor.py :language: python ``` 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 ```{literalinclude} ../../examples/e05_spawn_from_erlang.py :language: python ``` ## Calling Python functions Any running node answers `rpc:call` and `erpc:call`; nothing has to be registered. See [Calling Python from Erlang](calling_python.md).