pyrlang.node¶
The node: processes, names, and connections to other nodes.
- class pyrlang.node.SpawnResult(result, flags=0, exited=False, reason=None)¶
Bases:
objectWhat 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.
- 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:
objectAn 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 calldestroy()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
- unlink_counter_¶
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
Processobjects 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.exitmethod on the process.
- spawnables_: Dict[tuple[str, str], Callable[[...], Process]]¶
What other nodes may spawn: (module, function) -> factory.
- 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.
- 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;rexandnet_kernelstart here.
- async wait_started()¶
Wait until the node accepts connections and is registered in EPMD (if it uses EPMD).
- Raises:
EPMDConnectionError – EPMD cannot be reached, or refused the node name
OSError – the node cannot listen on its port
NodeException – the node was destroyed before it started
- async connect(node_name, host, port)¶
Connect to the node
node_namethat listens onhost:port, without asking EPMD (a node started with-erl_epmd_portorERL_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)(andspawn_link,spawn_monitor,spawn_opt,spawn_request) callsfactory(*Args), which must return a newProcess; its pid is what Erlang gets. Thelinkandmonitoroptions 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
parenton another node: start what is registered formodule:functionand set up the link and monitor the options ask for (req_idis 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,badargfor an argument list that is not a list.erpc:execute_call/4anderpc:execute_cast/3(whatrpc:call,erpc:calland their casts spawn) call a Python function likerexdoes.
- create_alias(pid)¶
A new alias for the local process
pid: a reference thatsend()and other nodes accept as a destination. Usepyrlang.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:
- register_new_process(proc=None)¶
Generate a new pid and add the process to the process dictionary.
- 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)
- where_is_process(ident)¶
Look up a registered name or pid.
- local_pid_of(dest)¶
The pid on this node that
deststands 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.
- 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_limitbytes wait to be sent on it.- Raises:
NodeException – the receiver’s node is not known to EPMD
EPMDConnectionError – the node’s EPMD cannot be asked
DistributionError – the handshake with the node fails
- 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
nameis established.- Returns:
False if there is none after
timeoutseconds- Return type:
- 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_cookie()¶
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 assend()does.- Parameters:
- Raises:
NodeException – if the node is not known to EPMD
EPMDConnectionError – if the node’s EPMD cannot be asked
DistributionError – if the handshake with the node fails
- link_nowait(pid1, pid2, local_only=False)¶
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.
- async link(pid1, pid2, local_only=False)¶
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.
- unlink_nowait(pid1, pid2, local_only=False)¶
unlink()for sync code: nothing waits for the connection.
- async unlink(pid1, pid2, local_only=False)¶
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.
- on_link(from_pid, to_pid)¶
A LINK signal:
from_pid(remote) links toto_pid(local).
- on_unlink_id(from_pid, to_pid)¶
An UNLINK_ID signal (the connection has sent the ack already).
- on_unlink_id_ack(unlink_id, from_pid, to_pid)¶
An UNLINK_ID_ACK signal for an unlink
to_pid(local) started.
- on_link_exit(from_pid, to_pid, reason)¶
An exit signal due to a link:
from_pidexited, or it is on a node the connection to which was lost.to_pid(local) reacts only if its link is active; reasonnormaljust ends the link.
- on_dist_node_down(node_name)¶
The connection to
node_nameis gone, or could not be set up. As in OTP, every link and monitor over it ends with reasonnoconnection: 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 thetarget, a special message will be sent to theorigin. Remote targets are supported.- Parameters:
- Raises:
pyrlang.errors.ProcessNotFoundError – if target does not exist.
- async demonitor_process(origin_pid, target, ref)¶
Locate the process
targetand remove theoriginfrom itsmonitors_collection. This does not trigger any notifications or signals to theorigin.- Parameters:
- Raises:
pyrlang.errors.ProcessNotFoundError – if target does not exist
- on_demonitor(origin_pid, target, ref)¶
A DEMONITOR_P signal: the remote
origin_pidremoves its monitorrefon the localtarget, if that is still there.
- on_monitor_exit(monitored, owner, ref, reason)¶
The monitor
refthat the local processownerholds onmonitoredfired. Unless it was removed before, the monitor ends andownergets{'DOWN', Ref, process, Monitored, Reason}; as in OTP, a demonitored monitor delivers nothing.
- release_monitor(origin, target, ref)¶
Remove the monitor
refthat the localoriginholds ontarget, becauseoriginexits: 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
ownerof a monitor thatmonitored(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’.
- send_link_exit_notification(sender, receiver, reason)¶
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.