pyrlang.node

The node: processes, names, and connections to other nodes.

class pyrlang.node.SpawnResult(result, flags=0, exited=False, reason=None)

Bases: object

What became of a spawn request: the content of the SPAWN_REPLY and, for a process that was over before the reply, the exit reason for its link and monitor.

result: Pid | Atom
flags: int = 0
exited: bool = False
reason: Any = None
class pyrlang.node.Node(node_name, cookie, hidden=False, net_ticktime=60, max_fragmented_size=268435456, epmd=True, dist_port=0, host=None, dist_buf_busy_limit=1048576, recv_backlog_messages=10000, recv_backlog_bytes=33554432)

Bases: object

An Erlang node: it has a name on the network, keeps the Python processes and their registered names, registers in EPMD, and connects to other nodes as messages need it.

Create it inside a running event loop, before any Process, and call destroy() when done. One node can be active in a Python process at a time.

node_db = <pyrlang.node_db.NodeDB object>

All existing local Node objects indexed by node_name: str

node_name_: str

Node name as seen on the network. Use full node names here: name@hostname

inbox_: Queue[Any]

Contains Pyrlang’s own messages to the local node.

The last unlink id used: ids are 1..2^64-1 and unique among the unacknowledged UNLINK_ID signals of this node.

processes_: Dict[Pid, Process]

Process dictionary which stores all the existing Process objects adressable by a pid.

Note

This creates a python reference to an object preventing its automatic garbage collection. In the end of its lifetime an object must be explicitly removed from this dictionary using Process.exit method on the process.

reg_names_: Dict[Atom, Pid]

Registered objects dictionary, which maps atoms to pids

spawnables_: Dict[tuple[str, str], Callable[[...], Process]]

What other nodes may spawn: (module, function) -> factory.

aliases_: Dict[Reference, Pid]

Active process aliases (EEP 53) of this node’s processes.

node_opts_

Distribution options object with feature support flags packed into an integer. The remote node will receive these flags to know what features we can support.

dist_nodes_: Dict[str, BaseDistProtocol]

Established connections by peer node name.

rex_: Rex | None
net_kernel_: NetKernel | None
adopt_name(node_name, creation)

Give a node that was created without a name the name and creation another node chose for it (the handshake status named:). From now on the node can have processes; rex and net_kernel start here.

async wait_started()

Wait until the node accepts connections and is registered in EPMD (if it uses EPMD).

Raises:
async connect(node_name, host, port)

Connect to the node node_name that listens on host:port, without asking EPMD (a node started with -erl_epmd_port or ERL_DIST_PORT, or one whose port is known otherwise). Messages to that node then use this connection. Does nothing if the node is connected already.

Raises:

DistributionError – the node cannot be reached or the handshake fails

async handle_signals()

The node’s own loop: lets processes act on their exit signals.

signal_wake_up(pid)

A process has a signal waiting; have it handled soon.

on_exit_process(exiting_pid, reason)

A process has exited: forget it and its registered names.

register_spawnable(module, function, factory)

Let other nodes spawn a Python process: Erlang’s spawn(Node, module, function, Args) (and spawn_link, spawn_monitor, spawn_opt, spawn_request) calls factory(*Args), which must return a new Process; its pid is what Erlang gets. The link and monitor options are honoured. If the factory raises, the spawned process counts as having exited with the exception as its reason.

on_spawn_request(req_id, parent, module, function, options, args)

A SPAWN_REQUEST from parent on another node: start what is registered for module:function and set up the link and monitor the options ask for (req_id is the monitor’s reference).

As on an Erlang node, a request that cannot run still gets a pid; that process is over at once: reason {undef, [{M, F, Args, []}]} for an unknown function, badarg for an argument list that is not a list. erpc:execute_call/4 and erpc:execute_cast/3 (what rpc:call, erpc:call and their casts spawn) call a Python function like rex does.

create_alias(pid)

A new alias for the local process pid: a reference that send() and other nodes accept as a destination. Use pyrlang.process.Process.alias(), which also removes the alias when the process exits.

remove_alias(alias)

Deactivate an alias: messages sent to it from now on are dropped.

Returns:

True if the alias was active

Return type:

bool

register_new_process(proc=None)

Generate a new pid and add the process to the process dictionary.

Parameters:

proc (Process | None) – A new process which needs a pid, or None if you only need a fake pid

Returns:

A new pid (does not modify the process in place, so please store the pid!)

Return type:

Pid

anonymous_pid()

A pid of this node that belongs to no process: the sender of messages sent without one to a registered name on another node, where the protocol wants a pid.

register_name(proc, name)

Add a name into registrations table (automatically removed when the referenced process is removed)

Parameters:
  • proc (Process) – The process to register

  • name (Atom) – The name to register with

where_is_process(ident)

Look up a registered name or pid.

local_pid_of(dest)

The pid on this node that dest stands for: a pid of this node itself, a registered name or an active alias. None for anything else.

where_is(ident)

Look up a registered name or pid.

Parameters:

ident (Atom | Pid) – an Atom or a Pid to convert to a Pid

send_nowait(sender, receiver, message)

Send a message from sync code, as send() does, without waiting: a local process gets it at once, a message to another node is queued behind everything sent to that node before (also while the connection is being set up). Messages to a node that cannot be reached are dropped and logged.

async send(sender, receiver, message)

Deliver a message to a pid or to a registered name. The pid may be located on another Erlang node. Messages from one sender to one receiver arrive in the order sent, whether sent with this method or send_nowait().

The message is delivered or queued before the first wait. Then this waits until the connection to the receiver’s node is set up, and while more than dist_buf_busy_limit bytes wait to be sent on it.

Raises:
Parameters:
  • sender (Pid | None) – Message sender

  • receiver (Pid | Atom | Reference | tuple[Any, Any]) – Message receiver, a pid, or a name, or a process alias (a message to an alias that is not active is dropped silently; an alias on another node needs sender), or a tuple with node name and a receiver on the remote node.

  • message (Any) – Any value which will be placed into the receiver inbox. Pyrlang processes use tuples but that is not enforced for your own processes.

register_dist_node(addr, proto)

add the protocol to dist nodes so that we can use it :param addr: :param proto: :return:

async wait_dist_node(name, timeout)

Wait until a connection to the node name is established.

Returns:

False if there is none after timeout seconds

Return type:

bool

unregister_dist_node(addr)

remove dist node (disconnected most likley) :param addr: :return:

on_alias_send(sender, alias, message)

A message for a process alias of this node, from a local sender or another node. Dropped if the alias is not active (removed, its process gone, or not one of this node’s references).

Get string cookie value for this node. TODO: Cookie per connection?

async dist_command(receiver_node, message)

Send a signal to another node: queue the tuple, crafted by the caller for the connection (("send", From, To, Msg), …), behind everything sent to that node before. Then wait as send() does.

Parameters:
  • receiver_node (str) – Name of a remote node

  • message (tuple[Any, ...]) – A crafted tuple with command name and some more values

Raises:

link() for sync code: the link is made, and the LINK signal queued behind what was sent before, when this returns; nothing waits for the connection.

Link two processes, at least one of them local. A local process gets the link at once; a remote one is sent a LINK signal, unless the local process already has an active link to it. Then this waits as send() does.

Parameters:
  • pid1 (Pid) – First pid

  • pid2 (Pid) – Second pid

  • local_only (bool) – If set to True, nothing is sent to a remote pid

unlink() for sync code: nothing waits for the connection.

Unlink two processes, at least one of them local. Towards a remote process this starts the unlink protocol: UNLINK_ID is sent and the link is inactive from now on; the remote side acknowledges later. Then this waits as send() does.

Parameters:
  • pid1 (Pid) – First pid

  • pid2 (Pid) – Second pid

  • local_only (bool) – If set to True, nothing is sent to a remote pid and the link is dropped at once

A LINK signal: from_pid (remote) links to to_pid (local).

An UNLINK_ID signal (the connection has sent the ack already).

An UNLINK_ID_ACK signal for an unlink to_pid (local) started.

An exit signal due to a link: from_pid exited, or it is on a node the connection to which was lost. to_pid (local) reacts only if its link is active; reason normal just ends the link.

on_dist_node_down(node_name)

The connection to node_name is gone, or could not be set up. As in OTP, every link and monitor over it ends with reason noconnection: local processes get the exit signal or the ‘DOWN’ message, once each; the monitors that processes of that node held on local ones end silently.

monitor_process(origin_pid, target, ref=None)

Locate the process referenced by the target and place the origin pid into its monitors_ collection. When something happens to the target, a special message will be sent to the origin. Remote targets are supported.

Parameters:
  • ref (Reference | None) – If not None, will be reused, else a new random ref will be generated.

  • origin_pid (Pid) – The (possibly remote) process who will be monitoring the target from now and wants to know when we exit.

  • target (Atom | Pid) – Name or pid of a monitor target process.

Raises:

pyrlang.errors.ProcessNotFoundError – if target does not exist.

async demonitor_process(origin_pid, target, ref)

Locate the process target and remove the origin from its monitors_ collection. This does not trigger any notifications or signals to the origin.

Parameters:
  • ref (Reference) – Reference which you received when setting up a monitor.

  • origin_pid (Pid) – The process who was monitoring the target before

  • target (Atom | Pid) – Name or pid of a monitor target process, possibly it does not exist

Raises:

pyrlang.errors.ProcessNotFoundError – if target does not exist

on_demonitor(origin_pid, target, ref)

A DEMONITOR_P signal: the remote origin_pid removes its monitor ref on the local target, if that is still there.

on_monitor_exit(monitored, owner, ref, reason)

The monitor ref that the local process owner holds on monitored fired. Unless it was removed before, the monitor ends and owner gets {'DOWN', Ref, process, Monitored, Reason}; as in OTP, a demonitored monitor delivers nothing.

release_monitor(origin, target, ref)

Remove the monitor ref that the local origin holds on target, because origin exits: at once for a local target, with DEMONITOR_P for a remote one.

destroy()

Closes incoming and outgoing connections and destroys the local node. This is Python, so some refs from running async handlers may remain.

exit_process(sender, receiver, reason)

Send an exit signal (Erlang’s exit/2) to a local or remote process. One to another node is queued behind what was sent there before; nothing waits.

send_monitor_exit(monitored, owner, ref, reason)

Tell the remote owner of a monitor that monitored (a local process, or the name it was monitored by) is down: MONITOR_P_EXIT. If that node is gone, its monitor ended with ‘noconnection’.

Deliver the exit signal of a link from sender, which exits, to a local or remote process. If the receiver’s node is gone, it saw ‘noconnection’ for the link.

get_loop()

The event loop the node runs in.

run()

Run the event loop until the node is destroyed. For a program that does not use asyncio.run.