4 files changed, 140 insertions, 1 deletions
diff --git a/erts/doc/src/Makefile b/erts/doc/src/Makefile
index 5fa8b0673a..96cc4413a9 100644
--- a/erts/doc/src/Makefile
+++ b/erts/doc/src/Makefile
@@ -74,6 +74,7 @@ XML_CHAPTER_FILES = \
 	match_spec.xml \
 	crash_dump.xml \
 	alt_dist.xml \
+	alt_disco.xml \
 	driver.xml \
 	absform.xml \
 	inet_cfg.xml \
diff --git a/erts/doc/src/alt_disco.xml b/erts/doc/src/alt_disco.xml
new file mode 100644
index 0000000000..d04221b9b3
--- /dev/null
+++ b/erts/doc/src/alt_disco.xml
@@ -0,0 +1,93 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2018</year><year>2018</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.
+
+    </legalnotice>
+
+    <title>How to Implement an Alternative Service Discovery for Erlang Distribution
+    </title>
+    <prepared>Timmo Verlaan</prepared>
+    <responsible></responsible>
+    <docno></docno>
+    <approved></approved>
+    <checked></checked>
+    <date>2018-04-25</date>
+    <rev>PA1</rev>
+    <file>alt_disco.xml</file>
+  </header>
+  <p>
+    This section describes how to implement an alternative discovery mechanism
+    for Erlang distribution. Discovery is normally done using DNS and the
+    Erlang Port Mapper Daemon (EPMD) for port discovery.
+  </p>
+
+  <note><p>
+    Support for alternative service discovery mechanisms was added in Erlang/OTP
+    21.
+  </p></note>
+
+
+  <section>
+    <title>Introduction</title>
+    <p>To implement your own service discovery module you have to write your own
+    EPMD module. The <seealso marker="kernel:erl_epmd">EPMD module</seealso> is
+    responsible for providing the location of another node. The distribution
+    modules (<c>inet_tcp_dist</c>/<c>inet_tls_dist</c>) call the EPMD module to
+    get the IP address and port of the other node. The EPMD module that is part
+    of Erlang/OTP will resolve the hostname using DNS and uses the EPMD unix
+    process to get the port of another node. The EPMD unix process does this by
+    connecting to the other node on a well-known port, port 4369.</p>
+  </section>
+
+  <section>
+    <title>Discovery module</title>
+    <p>The discovery module needs to implement the same API as the regular
+    <seealso marker="kernel:erl_epmd">EPMD module</seealso>. However, instead of
+    communicating with EPMD you can connect to any service to find out
+    connection details of other nodes. A discovery module is enabled
+    by setting <seealso marker="erts:erl#epmd_module">-epmd_module</seealso>
+    when starting erlang. The discovery module must implement the following
+    callbacks:</p>
+
+    <taglist>
+      <tag><seealso marker="kernel:erl_epmd#start_link/0">start_link/0</seealso></tag>
+      <item>Start any processes needed by the discovery module.</item>
+      <tag><seealso marker="kernel:erl_epmd#names/1">names/1</seealso></tag>
+      <item>Return node names held by the registrar for the given host.</item>
+      <tag><seealso marker="kernel:erl_epmd#register_node/2">register_node/2</seealso></tag>
+      <item>Register the given node name with the registrar.</item>
+      <tag><seealso marker="kernel:erl_epmd#port_please/3">port_please/3</seealso></tag>
+      <item>Return the distribution port used by the given node.</item>
+    </taglist>
+
+    <p>The discovery module may implement the following callback:</p>
+
+    <taglist>
+      <tag><seealso marker="kernel:erl_epmd#address_please/3">address_please/3</seealso></tag>
+      <item><p>Return the address of the given node.
+        If not implemented, <seealso marker="kernel:inet#gethostbyname/1">
+        inet:gethostbyname/1</seealso> will be used instead</p>
+        <p>This callback may also return the port of the given node. In that case
+        <seealso marker="kernel:erl_epmd#port_please/3">port_please/3</seealso>
+        may be omitted.</p></item>
+    </taglist>
+  </section>
+</chapter>
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 3154fdaf8c..cff56b9cb8 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -7005,10 +7005,47 @@ ok
               from other events in the system. It is only guaranteed that
               <c><anno>Suspendee</anno></c> <em>eventually</em> suspends
               (unless it
-              is resumed). If option <c>asynchronous</c> has <em>not</em>
+              is resumed). If no <c>asynchronous</c> options has
               been passed, the caller of <c>erlang:suspend_process/2</c> is
               blocked until <c><anno>Suspendee</anno></c> has suspended.</p>
           </item>
+          <tag><c>{asynchronous, ReplyTag}</c></tag>
+          <item>
+            <p>A suspend request is sent to the process identified by
+              <c><anno>Suspendee</anno></c>. When the suspend request
+	      has been processed, a reply message is sent to the caller
+	      of this function. The reply is on the form <c>{ReplyTag,
+	      State}</c> where <c>State</c> is either:</p>
+	      <taglist>
+		<tag><c>exited</c></tag>
+		<item>
+		  <p>
+		    <c><anno>Suspendee</anno></c> has exited.
+		  </p>
+		</item>
+		<tag><c>suspended</c></tag>
+		<item>
+		  <p>
+		    <c><anno>Suspendee</anno></c> is now suspended.
+		  </p>
+		</item>
+		<tag><c>not_suspended</c></tag>
+		<item>
+		  <p>
+		    <c><anno>Suspendee</anno></c> is not suspended.
+		    This can only happen when the process that
+		    issued this request, have called
+		    <c>resume_process(<anno>Suspendee</anno>)</c>
+		    before getting the reply.
+		  </p>
+		</item>
+	      </taglist>
+	      <p>
+		Appart from the reply message, the <c>{asynchronous,
+		ReplyTag}</c> option behaves exactly the same as the
+		<c>asynchronous</c> option without reply tag.
+	      </p>
+          </item>
           <tag><c>unless_suspending</c></tag>
           <item>
             <p>The process identified by <c><anno>Suspendee</anno></c> is
@@ -7032,6 +7069,13 @@ ok
         <warning>
           <p>This BIF is intended for debugging only.</p>
         </warning>
+	<warning>
+	  <p>You can easily create deadlocks if processes suspends
+	  each other (directly or in circles). In ERTS versions prior
+	  to ERTS version 10.0, the runtime system prevented such
+	  deadlocks, but this prevention has now been removed due
+	  to performance reasons.</p>
+	</warning>
         <p>Failures:</p>
         <taglist>
           <tag><c>badarg</c></tag>
diff --git a/erts/doc/src/part.xml b/erts/doc/src/part.xml
index d583b873a0..fc39cb30e6 100644
--- a/erts/doc/src/part.xml
+++ b/erts/doc/src/part.xml
@@ -37,6 +37,7 @@
   <xi:include href="match_spec.xml"/>
   <xi:include href="crash_dump.xml"/>
   <xi:include href="alt_dist.xml"/>
+  <xi:include href="alt_disco.xml"/>
   <xi:include href="absform.xml"/>
   <xi:include href="tty.xml"/>
   <xi:include href="driver.xml"/>