From 6b267b203c950db2879f254b6a9d3b7591115f9d Mon Sep 17 00:00:00 2001
From: Rickard Green
This section was written a long time ago. Most of it is still
- valid, but some things have changed since then.
- Most notably is the driver interface. Some updates have been made
- to the documentation of the driver presented here,
- but more can be done and is planned for the future.
- The reader is encouraged to read the
-
To implement a new carrier for the Erlang distribution, the main steps are as follows.
+
+ As of ERTS version 10.0 support for distribution controller
+ processes has been introduced. That is, the traffic over a
+ distribution channel can be managed by a process instead of
+ only by a port. This makes it possible to implement large
+ parts of the logic in Erlang code, and you perhaps do not
+ even need a new driver for the protocol. One example could
+ be Erlang distribution over UDP using
First, the protocol must be available to the Erlang machine, which @@ -151,8 +153,635 @@
+ The distribution module expose an API that
+ The module needs to create some kind of listening entity (process + or port) and an acceptor process that accepts incoming connections + using the listening entity. For each connection, the module at least + needs to create one connection supervisor process, which also is + responsible for the handshake when setting up the connection, and + a distribution controller (process or port) responsible for + transport of data over the connection. The distribution controller + and the connection supervisor process should be linked together + so both of them are cleaned up when the connection is taken down. +
++ Note that there need to be exactly one distribution controller + per connection. A process or port can only be distribution + controller for one connection. The registration as distribution + controller cannot be undone. It will stick until the distribution + controller terminates. The distribution controller should not + ignore exit signals. It is allowed to trap exits, but it should + then voluntarily terminate when an exit signal is received. +
+ ++ The following functions are mandatory: +
+
+
+ The return value consists of a
+ If
+
+ The
+ The caller of this function is a representative for
+
+
+ The request was accepted and
+ The request was rejected. This is a fatal error. The acceptor + process should terminate. +
++ When an accept sequence has been completed the acceptor process + is expected to continue accepting further requests. +
+
+
The arguments:
+
+ Process identifier of the process created by the
+
The identifier of the distribution controller identifier
+ created by the acceptor process. To be passed along to
+
+ Node name of this node. To be passed along to
+
+ To be passed along to
+
+ Time used for creating a setup timer by a
+ call to
+ The created process should provide callbacks and other
+ information needed for the handshake in a
+
+
+
The arguments:
+
+ Node name of remote node. To be passed along to
+
+ Connection type. To be passed along to
+
+ Node name of this node. To be passed along to
+
+ Either the atom
+ Time used for creating a setup timer by a
+ call to
+ The caller of this function is a representative for
+ This function should, besides spawning the connection supervisor, + also create a distribution controller. The distribution + controller is either a process or a port which is responsible + for dispatching traffic. +
+
+ The created process should provide callbacks and other
+ information needed for the handshake in a
+
+
+ Called in order to close the
Return
+ There are also two optional functions that may be + exported: +
+
+ The argument
+ The argument
+ The
+ The following
+ Process identifier of the
Name of the other node. This field is only
+ mandatory when this node initiates the connection.
+ That is, when connection is set up via
+
+ The node name of this node. +
++ The identifier of the distribution controller. +
+
+ The timer created using
Information passed as
+ A fun with the following signature: +
+ ok | {error, Error}]]>
+
+ where
Only used during handshake phase.
++ A fun with the following signature: +
+ {ok, Packet} | {error, Reason}]]>
+
+ where
Only used during handshake phase.
++ A fun with the following signature: +
+ ok | {error, Error}]]>
+
+ where
Only used during handshake phase.
++ A fun with the following signature: +
+ ok | {error, Error}]]>
+
+ where
Only used during handshake phase.
++ A fun with the following signature: +
+ ID]]>
+
+ where
Only used during handshake phase.
++ A fun with the following signature: +
+ NetAddress]]>
+
+ where
Only used during handshake phase.
++ A fun with the following signature: +
+ void()]]>
+
+ where
+ It is of vital importance that this operation + does not block the caller for a long time. + This since it is called from the connection + supervisor. +
Used when connection is up.
++ A fun with the following signature: +
+ {ok, Received, Sent, PendSend}]]>
+
+ where
+ It is of vital importance that this operation + does not block the caller for a long time. + This since it is called from the connection + supervisor. +
Used when connection is up.
+
+ The request
+ A fun with the following signature: +
+ ok | {error, Error}]]>
+
+ where
This function is optional. Used when connection is up.
++ A fun with the following signature: +
+ {ok, OptionValues} | {error, Error}]]>
+
+ where
This function is optional. Used when connection is up.
++ A fun with the following signature: +
+ void()]]>
+
+ where
+ This function is called when the handshake has + completed and the distribution channel is up. + The distribution controller can begin dispatching + traffic over the channel. This function is optional. +
+Only used during handshake phase.
+For
If no
This section was written a long time ago. Most of it is still
+ valid, but some things have changed since then. Some updates have
+ been made to the documentation of the driver presented here,
+ but more can be done and is planned for the future.
+ The reader is encouraged to read the
+
Although Erlang drivers in general can be beyond the scope of this section, a brief introduction seems to be in place.
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 105734d5b2..8b0f97f30f 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -181,6 +181,14 @@ + +An opaque handle identifing a distribution channel.
+
+ Get distribution channel data from the local node that is
+ to be passed to the remote node. The distribution channel
+ is identified by
+ The data retreived from this function needs to be delivered + as is to the node on the other end in the exact same order, + with no loss of data what so ever, as retrived from this + function. +
+ Only the process registered as distribution
+ controller for the distribution channel identified by
+
+ This function is used when implementing an alternative
+ distribution carrier using processes as distribution
+ controllers.
+ Request notification when more data is available to
+ fetch using
+
+ Only the process registered as distribution
+ controller for the distribution channel identified by
+
+ This function is used when implementing an alternative
+ distribution carrier using processes as distribution
+ controllers.
+ Register an alternate input handler process for the
+ distribution channel identified by
+ Only the process registered as distribution
+ controller for the distribution channel identified by
+
+ This function is used when implementing an alternative
+ distribution carrier using processes as distribution
+ controllers.
+ Deliver distribution channel data from a remote node to the + local node. +
++ The data passed to the VM using this function needs to be + passed in the exact same order, and with no loss of data + what so ever, as sent from the node on the other end. +
+ Only the process registered as distribution
+ controller for the distribution channel identified by
+
+ This function is used when implementing an alternative
+ distribution carrier using processes as distribution
+ controllers.
+ An example implementation of a distribution module can be found
+ in
+
Only used during handshake phase.
+ +
+
+ This flag field is optional. +
+
+
+ This flag field is optional. +
+
+ Require these
+ This flag field is optional. +
++ When using the default configuration, the data to pass + over a connection needs to be delivered as is + to the node on the receiving end in the exact same + order, with no loss of data what so ever, as sent + from the sending node. +
+
+ The data delivery order can be relaxed by disabling
+ features that require strict ordering. This is done by
+ passing the
The node understand UTF-8 encoded atoms.
The node understand the map tag.
+The node understand big node creation.
+
+ Use the
+ There are also a collection of
The
Followed by
+ This control messages replace the
+ Messages encoded before the connection has
+ been set up may still use the
Followed by
+ This control messages replace the
+ Messages encoded before the connection has
+ been set up may still use the
- The data retreived from this function needs to be delivered - as is to the node on the other end in the exact same order, - with no loss of data what so ever, as retrived from this - function. -
Only the process registered as distribution
controller for the distribution channel identified by
@@ -1253,7 +1247,7 @@ end
controllers.
- The data passed to the VM using this function needs to be - passed in the exact same order, and with no loss of data - what so ever, as sent from the node on the other end. -
Only the process registered as distribution
controller for the distribution channel identified by
@@ -1360,7 +1349,7 @@ end
controllers.