Clause
← All dokumentation

Den här sidan är inte översatt ännu och visas därför på engelska.

Distribution

How a Clause executable becomes a distributed Erlang node. Decided; the steps that implement it are in the project plan.

Today a program is a non-distributed node, nonode@nohost. Pids, ports and references of other nodes exist as terms (terms), the node can be named (this node), connection entries, node status messages, node monitors and the controller data path follow OTP's process-controller interface without moving any signal yet (connections). erl_epmd and net_adm:names/0,1 speak to an epmd, and Clause's epmd server runs as clause-epmd (epmd; written beside programs with -daemon, -names and -kill) or inside the program when a registration finds none (--epmd bundled); --epmd external starts an epmd program, and --no-bundled-epmd leaves the bundled epmd out. net_kernel:start/1,2 and stop/0 start and end distribution in a running program (starting distribution), and --sname/--name before the entry (node start options), with OTP's cookies (cookies). Nodes connect through OTP's handshake with all its statuses, allow/1 and dynamic names (making connections), over IPv4 or IPv6, messages move between them (messages), processes monitor other nodes' processes and net_adm:ping/1 answers (process monitors), and they link and send exit signals to each other (links and exit signals), and lead each other's processes (group leaders) and spawn processes on each other (spawning), every signal of a pair of processes in the order sent (signal order). Clause and OTP 29 nodes connect, ping, monitor, message, link, lead and spawn on each other both ways on either kind of epmd (testing). net_kernel changes tick times, reports and tunes connections, and auth keeps cookies as OTP's (managing connections, cookies). The other libraries answer as OTP does without distribution ({badrpc, nodedown}, not_alive). The rest of this file is the contract for distribution. Each section becomes current behavior when its step lands.

Scope

Protocol

Runtime and libraries

The work is split as in OTP: the runtime moves signals, and Erlang code makes connections.

This node

Current (builtins/erlang/node.cpp, scheduler/signals.cpp), as in OTP:

Connections

Current (scheduler/connections.cpp, builtins/erlang/connections.cpp), as OTP's process-controller interface. Signals move over it (messages); the controller reads and writes through the controller data path. Node monitors hold entries too (node monitors).

Node monitors

Current (scheduler/connections.cpp, builtins/erlang/node.cpp), as OTP's:

Controller data path

Current (builtins/erlang/connections.cpp), as OTP's. A connection has an output queue of encoded packets, which messages fill (messages), also while it is pending, and an up connection an input handler, first the controller.

Messages

Current (builtins/erlang/dist_messages.cpp), as OTP 29's, observed with a peer speaking the protocol and with a test process as a connection's controller.

Process monitors

Current (scheduler/remote_monitors.cpp), as OTP 29's dist.c, observed with a test process as a connection's controller and between two nodes.

Current (scheduler/remote_links.cpp), as OTP 29's dist.c, observed with a test process as a connection's controller and between two nodes.

Group leaders

Current (builtins/erlang/dist_messages.cpp), as OTP 29's.

Spawning

Current (scheduler/remote_spawns.cpp, builtins/erlang/dist_spawns.cpp, library/kernel/clause_dist_spawn.erl), as OTP 29's dist.c and erlang.erl, observed with a test process as a connection's controller and between two nodes.

Signal order

Current, as OTP's. Every signal one process sends to another node (messages, links, unlinks, monitors, exit signals, group leaders, spawn requests) is a packet on that node's one connection, queued in the order sent, also while the connection is pending or being auto-connected; the packets of the other node are taken in the order its controller puts them, and each is acted on before the next. So signals between a pair of processes arrive in the order sent, as locally. While a connection is pending its packets use the forms of no flags (SEND without the sender, EXIT2 without payload), as OTP's do.

Node status messages

Current, as OTP's: process_flag(monitor_nodes, Bool), process_flag({monitor_nodes, Options}, Bool) and net_kernel:monitor_nodes/1,2 over them.

Carriers

User carriers are supported through OTP's interface, current (library/kernel/dist_util.erl, include/dist.hrl, include/dist_util.hrl):

Making connections

Current (library/kernel/dist_util.erl, inet_tcp_dist.erl, net_kernel.erl), as OTP's; the statuses other than ok, allow/1 and dynamic names.

Managing connections

Current (library/kernel/net_kernel.erl, dist_util.erl), as OTP's net_kernel:

epmd

Clause can provide epmd in two forms, built from the same C++ epmd code in the runtime. Both serve OTP's epmd protocol: ALIVE2 (with the ALIVE2_X reply), PORT_PLEASE2, NAMES, DUMP, KILL and STOP. A registration ends when its node's connection to epmd closes, and STOP and KILL are accepted only with -relaxed_command_check, as in OTP's epmd. ERL_EPMD_PORT (default 4369) and ERL_EPMD_ADDRESS work as for OTP's epmd.

The runtime option --epmd MODE chooses what happens when distribution starts, at startup or by net_kernel:start/1,2:

ModeWhen an epmd already listensWhen none listens
bundled (default)Register with itRun the bundled epmd inside the program, then register
externalRegister with itStart clause-epmd -daemon (the program's directory first, then PATH) or OTP's epmd -daemon from PATH, then register; distribution fails to start if neither is found
noneRegister with itDistribution fails to start

Current (runtime/src/epmd/, library/kernel/erl_epmd.erl):

Current (runtime/src/epmd/bundled.cpp, runtime/src/builtins/epmd.cpp):

Current (runtime/src/epmd/main.cpp, client.cpp, daemon_*.cpp, compiler/src/linking/link.cpp):

Current (runtime/src/epmd/extension.cpp, launch_*.cpp, library/kernel/clause_dist.erl):

Starting distribution

Current (library/kernel/net_kernel.erl, erl_distribution.erl, inet_tcp_dist.erl), as OTP's net_kernel:start/1,2 and stop/0. The started node connects to others as making connections says.

kernel_sup

Current (library/kernel/kernel.erl, clause_kernel.erl). OTP's node starts kernel_sup at boot; Clause starts it at the first use of a kernel service: rex (rpc), global_name_server (global), global_group, or distribution (net_kernel:start/1,2, --sname, --name). A program that uses none has none.

Cookies

Current (library/kernel/auth.erl, runtime/src/builtins/erlang/node.cpp), as OTP's auth:

Node start options

Runtime options (executables) start distribution before the entry runs. They can be given:

The command line wins over CLAUSE_FLAGS, which wins over the manifest.

OptionOTP counterpartEffect
--sname NAME-snameShort node name NAME@Host; NAME@HOST is taken as given
--name NAME-nameLong node name with the fully qualified host; undefined asks the first peer for a dynamic name
--setcookie COOKIE-setcookieThis node's cookie; otherwise ~/.erlang.cookie is read, or created as OTP creates it
--nocookie-nocookieNo cookie until erlang:set_cookie/1,2
--hidden-hiddenHidden node
--proto-dist PROTO-proto_distCarrier module PROTO_dist; default inet_tcp
--epmd bundled|external|none-start_epmdWhat to do when no epmd runs (epmd); default bundled
--dist-listen true|false-dist_listenAccept incoming connections; false implies --hidden
--env APP KEY VALUE-App Key ValueSets APP's environment parameter KEY to the term VALUE before applications start, over the .app resources (for example --env kernel net_ticktime 20). It works for every application, not only for distribution

Current (library/kernel/clause_dist_start.erl, erl_distribution.erl, runtime/src/startup/startup.cpp):

Testing