From b0900fc2f7daab1c77dd8878c39ab24591bb076b Mon Sep 17 00:00:00 2001
From: Xavier Noria <fxn@hashref.com>
Date: Thu, 5 Apr 2018 01:40:20 +0200
Subject: Explain why the AM becomes group leader

---
 erts/doc/src/erlang.xml                       |  9 ++++++++-
 lib/kernel/doc/src/application.xml            | 10 +++++++---
 lib/kernel/src/application_master.erl         |  4 ++++
 system/doc/design_principles/applications.xml | 10 +++++++---
 4 files changed, 26 insertions(+), 7 deletions(-)

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 1b973cd60e..984072076c 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -2068,8 +2068,15 @@ end</pre>
           Typically, this is used when a process started from a
           certain shell is to have another group leader than
           <c>init</c>.</p>
+        <p>The group leader should be rarely changed in
+          applications with a supervision tree, because OTP
+          assumes the group leader of their processes is
+          their application master.</p>
         <p>See also
-          <seealso marker="#group_leader/0"><c>group_leader/0</c></seealso>.</p>
+          <seealso marker="#group_leader/0"><c>group_leader/0</c></seealso>
+          and <seealso marker="doc/design_principles:applications#stopping">OTP
+          design principles</seealso> related to starting and stopping
+          applications.</p>
       </desc>
     </func>
 
diff --git a/lib/kernel/doc/src/application.xml b/lib/kernel/doc/src/application.xml
index 886286b76d..be914aee87 100644
--- a/lib/kernel/doc/src/application.xml
+++ b/lib/kernel/doc/src/application.xml
@@ -318,8 +318,13 @@ Nodes = [cp1@cave, {cp2@cave, cp3@cave}]</code>
           <c>{error,{not_started,App}}</c> is returned, where <c>App</c>
           is the name of the missing application.</p>
         <p>The application controller then creates an <em>application master</em>
-	  for the application. The application master is
-          the group leader of all the processes in the application.
+          for the application. The application master becomes the
+          group leader of all the processes in the application. I/O is
+          forwarded to the previous group leader, though, this is just
+          a way to identify processes that belong to the application.
+          Used for example to find itself from any process, or,
+          reciprocally, to kill them all when it terminates.</p>
+        <p>
           The application master starts the application by calling
           the application callback function <c>Module:start/2</c> as
           defined by the application specification key <c>mod</c>.</p>
@@ -608,4 +613,3 @@ Nodes = [cp1@cave, {cp2@cave, cp3@cave}]</code>
       <seealso marker="app">app(4)</seealso></p>
   </section>
 </erlref>
-
diff --git a/lib/kernel/src/application_master.erl b/lib/kernel/src/application_master.erl
index 5da2b0b06c..06991b45e1 100644
--- a/lib/kernel/src/application_master.erl
+++ b/lib/kernel/src/application_master.erl
@@ -118,6 +118,10 @@ init(Parent, Starter, ApplData, Type) ->
     link(Parent),
     process_flag(trap_exit, true),
     OldGleader = group_leader(),
+    %% We become the group leader, but forward all I/O to OldGleader.
+    %% This is just a way to identify processes that belong to the
+    %% application. Used for example to find ourselves from any
+    %% process, or, reciprocally, to kill them all when we terminate.
     group_leader(self(), self()),
     %% Insert ourselves as master for the process.  This ensures that
     %% the processes in the application can use get_env/1 at startup.
diff --git a/system/doc/design_principles/applications.xml b/system/doc/design_principles/applications.xml
index c673fde07e..6e5a2ce6cf 100644
--- a/system/doc/design_principles/applications.xml
+++ b/system/doc/design_principles/applications.xml
@@ -363,9 +363,13 @@ ok
       application are running.</p>
     <marker id="application_master"></marker>
     <p>The application controller then creates an
-    <em>application master</em> for the application. The application master
-      is the group leader of all the processes in the application.
-      The application master starts the application by calling
+      <em>application master</em> for the application. The application
+      master becomes the group leader of all the processes in the
+      application. I/O is forwarded to the previous group leader,
+      though, this is just a way to identify processes that belong to
+      the application. Used for example to find itself from any process,
+      or, reciprocally, to kill them all when it terminates.</p>
+    <p>The application master starts the application by calling
       the application callback function <c>start/2</c> in the module,
       and with the start argument, defined by the <c>mod</c> key in
       the <c>.app</c> file.</p>
-- 
cgit v1.2.3